Metadata-Version: 2.5
Name: immich-memories
Version: 1.0.0-rc.10
Summary: Watch your memories again, in films you can make your own.
Project-URL: Homepage, https://github.com/sam-dumont/immich-memories
Project-URL: Documentation, https://sam-dumont.github.io/immich-memories/
Project-URL: Repository, https://github.com/sam-dumont/immich-memories
Project-URL: Issues, https://github.com/sam-dumont/immich-memories/issues
Project-URL: Changelog, https://github.com/sam-dumont/immich-memories/releases
Author: Immich Memories Contributors
License-Expression: MIT
License-File: LICENSE
Keywords: compilation,immich,memories,photo-management,video
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Multimedia :: Video :: Conversion
Requires-Python: <3.14,>=3.11
Requires-Dist: alembic>=1.13
Requires-Dist: apprise>=1.9
Requires-Dist: babel>=2.18.0
Requires-Dist: click>=8.3.3
Requires-Dist: cryptography>=50.0.0
Requires-Dist: fastapi>=0.135
Requires-Dist: freetype-py>=2.4
Requires-Dist: geopy>=2.5.0
Requires-Dist: holidays>=0.105
Requires-Dist: httpx<1,>=0.27
Requires-Dist: itsdangerous>=2.2
Requires-Dist: nltk>=3.9.1
Requires-Dist: numpy>=1.24
Requires-Dist: opencv-python<6,>=5
Requires-Dist: pi-heif>=1.4
Requires-Dist: pillow>=12.3.0
Requires-Dist: psycopg[binary]>=3.2
Requires-Dist: pydantic-settings>=2.14.2
Requires-Dist: pydantic>=2.0
Requires-Dist: python-multipart>=0.0.31
Requires-Dist: pyyaml>=6.0
Requires-Dist: quadrants>=1.3.0; python_version < '3.14' and (sys_platform != 'darwin' or platform_machine != 'x86_64')
Requires-Dist: rich>=13.0
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: staticmap>=0.5
Requires-Dist: uvicorn>=0.30
Requires-Dist: watchdog>=3.0
Provides-Extra: all
Requires-Dist: authlib>=1.6.12; extra == 'all'
Requires-Dist: demucs>=4.0; extra == 'all'
Requires-Dist: huggingface-hub>=1.29; extra == 'all'
Requires-Dist: immich-memories-music>=0.1.0; extra == 'all'
Requires-Dist: kaldi-native-fbank>=1.20; extra == 'all'
Requires-Dist: onnxruntime>=1.28; extra == 'all'
Requires-Dist: soundfile>=0.13.1; extra == 'all'
Requires-Dist: tokenizers>=0.22; extra == 'all'
Provides-Extra: all-mac
Requires-Dist: demucs>=4.0; extra == 'all-mac'
Requires-Dist: huggingface-hub>=1.29; extra == 'all-mac'
Requires-Dist: immich-memories-music>=0.1.0; extra == 'all-mac'
Requires-Dist: kaldi-native-fbank>=1.20; extra == 'all-mac'
Requires-Dist: onnxruntime>=1.28; extra == 'all-mac'
Requires-Dist: pyobjc-core>=9.0; (sys_platform == 'darwin') and extra == 'all-mac'
Requires-Dist: pyobjc-framework-metal>=9.0; (sys_platform == 'darwin') and extra == 'all-mac'
Requires-Dist: pyobjc-framework-quartz>=9.0; (sys_platform == 'darwin') and extra == 'all-mac'
Requires-Dist: pyobjc-framework-vision>=9.0; (sys_platform == 'darwin') and extra == 'all-mac'
Requires-Dist: soundfile>=0.13.1; extra == 'all-mac'
Requires-Dist: tokenizers>=0.22; extra == 'all-mac'
Provides-Extra: auth
Requires-Dist: authlib>=1.6.12; extra == 'auth'
Provides-Extra: demucs
Requires-Dist: demucs>=4.0; extra == 'demucs'
Requires-Dist: soundfile>=0.13.1; extra == 'demucs'
Provides-Extra: dev
Requires-Dist: commitizen>=3.0; extra == 'dev'
Requires-Dist: deptry>=0.20; extra == 'dev'
Requires-Dist: diff-cover>=10.6.0; extra == 'dev'
Requires-Dist: grimp>=3.0; extra == 'dev'
Requires-Dist: hypothesis>=6.168.3; extra == 'dev'
Requires-Dist: import-linter>=2.15; extra == 'dev'
Requires-Dist: mypy>=2.4.0; extra == 'dev'
Requires-Dist: oidc-provider-mock>=0.3; extra == 'dev'
Requires-Dist: pillow-heif>=1.3; extra == 'dev'
Requires-Dist: pre-commit>=3.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=1.4.0; extra == 'dev'
Requires-Dist: pytest-benchmark>=5.3.0; extra == 'dev'
Requires-Dist: pytest-cov>=7.1.0; extra == 'dev'
Requires-Dist: pytest-playwright>=0.5; extra == 'dev'
Requires-Dist: pytest-xdist>=3.5; extra == 'dev'
Requires-Dist: pytest>=9.0.3; extra == 'dev'
Requires-Dist: python-semantic-release>=9.0; extra == 'dev'
Requires-Dist: refurb>=2.0; extra == 'dev'
Requires-Dist: ruff>=0.1; extra == 'dev'
Requires-Dist: soundfile>=0.12; extra == 'dev'
Requires-Dist: tokenizers>=0.22; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
Provides-Extra: editorial
Requires-Dist: huggingface-hub>=1.29; extra == 'editorial'
Requires-Dist: kaldi-native-fbank>=1.20; extra == 'editorial'
Requires-Dist: onnxruntime>=1.28; extra == 'editorial'
Requires-Dist: tokenizers>=0.22; extra == 'editorial'
Provides-Extra: editorial-cuda
Requires-Dist: huggingface-hub>=1.29; extra == 'editorial-cuda'
Requires-Dist: kaldi-native-fbank>=1.20; extra == 'editorial-cuda'
Requires-Dist: onnxruntime-gpu<1.27,>=1.26; (sys_platform == 'linux') and extra == 'editorial-cuda'
Requires-Dist: tokenizers>=0.22; extra == 'editorial-cuda'
Provides-Extra: mac
Requires-Dist: pyobjc-core>=9.0; (sys_platform == 'darwin') and extra == 'mac'
Requires-Dist: pyobjc-framework-metal>=9.0; (sys_platform == 'darwin') and extra == 'mac'
Requires-Dist: pyobjc-framework-quartz>=9.0; (sys_platform == 'darwin') and extra == 'mac'
Requires-Dist: pyobjc-framework-vision>=9.0; (sys_platform == 'darwin') and extra == 'mac'
Provides-Extra: music
Requires-Dist: immich-memories-music>=0.1.0; extra == 'music'
Description-Content-Type: text/markdown

# Immich Memories

[![CI](https://github.com/sam-dumont/immich-memories/actions/workflows/ci.yml/badge.svg)](https://github.com/sam-dumont/immich-memories/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/sam-dumont/immich-memories/graph/badge.svg)](https://codecov.io/gh/sam-dumont/immich-memories)
[![OpenSSF Scorecard](https://img.shields.io/ossf-scorecard/github.com/sam-dumont/immich-memories?label=openssf%20scorecard)](https://scorecard.dev/viewer/?uri=github.com/sam-dumont/immich-memories)
[![Release](https://github.com/sam-dumont/immich-memories/actions/workflows/release.yml/badge.svg)](https://github.com/sam-dumont/immich-memories/actions/workflows/release.yml)
[![Python](https://img.shields.io/pypi/pyversions/immich-memories)](https://pypi.org/project/immich-memories/)
[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
[![Docs](https://img.shields.io/badge/docs-Docusaurus-blue)](https://sam-dumont.github.io/immich-memories/)

**Watch your memories again, in films you can make your own.**

Immich Memories turns the photos and videos in your Immich library into MP4 films with titles
and music. Pick a month, a year, a trip, an album or a person. Review the proposed cut, swap what
you don't like, then render. A quiet month makes a short film rather than 3 minutes of filler.

It runs on a plain NAS with no GPU or text reader. Basic uses small local picture classifiers;
GPU adds descriptions and extra checks, and Full adds a text reader to refine the cut.

**[Quick start](#make-your-first-film)** · **[Documentation](https://sam-dumont.github.io/immich-memories/docs/)** · **[Install guides](https://sam-dumont.github.io/immich-memories/docs/run/overview)** · **[Demo](https://sam-dumont.github.io/immich-memories/demo/demo.mp4)**

<p align="center">
  <a href="https://sam-dumont.github.io/immich-memories/demo/demo.mp4">
    <picture>
      <source media="(prefers-color-scheme: dark)" srcset="https://sam-dumont.github.io/immich-memories/img/dark-demo-hero.gif">
      <img src="https://sam-dumont.github.io/immich-memories/img/demo-hero.gif" alt="Choose a memory, review and change its cut, and watch the finished film" width="720">
    </picture>
  </a>
  <br/>
  <sub><a href="https://sam-dumont.github.io/immich-memories/demo/demo.mp4">▶ Play the demo with music</a> · <a href="https://sam-dumont.github.io/immich-memories/demo/trip-preview.mp4">Watch a finished trip film</a> · Wikimedia Commons photographs under CC0 or CC BY, <a href="tests/e2e/fixtures/library/CREDITS.md">credited here</a> · <a href="https://sam-dumont.github.io/immich-memories/docs/">Documentation</a></sub>
</p>

## Make your first film

**Docker Compose is the recommended install. Start with Basic if you are unsure.** Every tier
makes a complete film, and you can change tiers later.

| Tier | What it adds | What it needs | Install |
|---|---|---|---|
| **Basic** | Dates, favourites, people, places and small picture classifiers guide the cut; up to 1080p. | 2 CPU cores and 4 GiB RAM for the app, in addition to Immich. | Follow the steps below. |
| **GPU** | Picture descriptions, document/sensitive-content checks and a family-viewing pre-screen. | NVIDIA services with the Container Toolkit, or native Apple Silicon. Allow 8 GiB for the Compose app plus its model services. | Select **GPU** in [Quick start](https://sam-dumont.github.io/immich-memories/docs/get-started/quick-start), or use [native Mac](https://sam-dumont.github.io/immich-memories/docs/run/uv-pip#apple-silicon). |
| **Full** | A text reader refines the cut, writes the film's summary and names special days. | The GPU setup plus an enabled reader with a 32k context window. | Select **Full** in [Quick start](https://sam-dumont.github.io/immich-memories/docs/get-started/quick-start). |

You need an existing Immich server, Docker Compose v2 and **about 25 GB of app data plus 0.35 GB per 1,000
pictures and videos in your library, plus images and finished films**. Immich v2 and v3 both work; the [deployment matrix](https://sam-dumont.github.io/immich-memories/docs/run/tested-deployments)
records tested versions. GPU services can run on another machine.
For a NAS container manager, [use its platform guide](https://sam-dumont.github.io/immich-memories/docs/run/nas).

1. **Download the two Basic files** into a new folder:

   ```bash
   mkdir -p immich-memories && cd immich-memories
   VERSION=1.0.0-rc.9
   curl -fLO "https://github.com/sam-dumont/immich-memories/releases/download/v${VERSION}/docker-compose.yml"
   curl -fLO "https://github.com/sam-dumont/immich-memories/releases/download/v${VERSION}/example.env"
   cp example.env .env
   ```

   `example.env` pins the app image to the same release. Keep `TIER=basic`.

2. **Edit `.env`** with your Immich address, API key and timezone:

   ```ini
   IMMICH_URL=http://192.168.1.10:2283
   IMMICH_API_KEY=your-api-key
   TZ=Etc/UTC
   ```

   In Immich, create the key under **Account Settings → API Keys** with the
   [ten read permissions](https://sam-dumont.github.io/immich-memories/docs/run/docker#the-api-key).
   Use an Immich address the container can reach; `localhost` means the container itself.

   To open the app from another computer on your LAN, also set these in `.env`:

   ```ini
   IMMICH_MEMORIES_AUTH_USERNAME=admin
   IMMICH_MEMORIES_AUTH_PASSWORD=replace-with-your-own-long-password
   UI_BIND_ADDRESS=0.0.0.0
   ```

   Choose a password of at least 12 characters. This is the **Immich Memories app login**.
   LAN access uses HTTP; [HTTPS setup](https://sam-dumont.github.io/immich-memories/docs/run/authentication#behind-a-reverse-proxy-with-tls)
   is separate. Otherwise, keep the default localhost binding.

3. **Prepare the output folder and start the app.** On Linux:

   ```bash
   mkdir -p output
   sudo chown 1000:1000 output
   chmod 600 .env
   docker compose up -d
   ```

   The app writes films as UID/GID 1000. For a Synology bind mount, use the
   [DSM folder permissions](https://sam-dumont.github.io/immich-memories/docs/run/nas#the-output-folder)
   instead of `chown`.

4. **Open the app** at `http://localhost:8080`, or `http://your-server-address:8080` for LAN
   access and sign in with the app login above. On **Memory**, click **Download models** and
   wait for the card to disappear. If no card or error appears, the required files are ready.

   Make [your first film](https://sam-dumont.github.io/immich-memories/docs/get-started/first-film)
   from an album of **20–50 photos and short videos**: choose **Album**, set the length to
   **0.5 minutes**, then **Cut**, review and **Render**. Leave upload off and use **Download film**
   to keep the MP4. A full month can take hours on a NAS; a small album limits the first preparation.

For a failed step, use [Installation help](https://sam-dumont.github.io/immich-memories/docs/reference/installation-help).
Once the first film works, [After install](https://sam-dumont.github.io/immich-memories/docs/get-started/after-install)
covers home, people, language, backups and automation.

## What you can do

- **Photos and videos in one film.** Stills get animated, videos give their best few seconds,
  and a Live Photo plays as motion when its clip lasts 2.5 s and actually moves. Favourites and
  named people win close calls. Every shot says why it's in the cut, and the pool shows
  everything that was left out.
- **Change the cut before rendering.** Remove a shot, trim a video, swap a picture or pull one
  in from the pool, then render that revision. "Never use" is a lasting decision, separate from
  dropping a shot from one film.
- **Titles and music out of the box.** A film is titled by what it is and when ("Summer 2025",
  "Kit's birthday · 2026") and gets a bundled track. Maps and generated music are optional
  extras with their own setup.
- **Automate it later.** A daily timer picks one memory worth making (a trip, a birthday, last
  month) and can upload it to Immich, with its title and story summary as the description, or
  keep it on disk. Make a few films by hand first.
- **Ask in your own words.** "our cat through the years" can become a film. Highly
  experimental: tuned on one real library, so preview before you trust it.
- **Add a GPU or a model when you want.** Basic makes complete films on a CPU. A GPU adds
  captions and extra picture checks, Full adds a text reader on top. A hardware encoder only
  speeds up rendering.

[How it chooses](https://sam-dumont.github.io/immich-memories/docs/how-it-chooses/overview)
explains the selection rules. [Improve a film](https://sam-dumont.github.io/immich-memories/docs/make/improve-a-film)
covers length, missing people and shot changes. What doesn't work yet is in the
[issue tracker](https://github.com/sam-dumont/immich-memories/issues).

## Access and privacy

The app talks to Immich with a scoped API key and never modifies your originals. Uploading a
film is opt-in. Model downloads, optional model servers, maps, notifications and workers each
have their own data flow, and a local URL alone doesn't prove nothing leaves.
[Privacy](https://sam-dumont.github.io/immich-memories/docs/run/privacy) lists every recipient
and how to check the Basic tier is offline.

**Turn on authentication before you open it to your LAN.** Authentication is disabled by default. Native installs
and the shipped Compose file listen on localhost only; change the port mapping and anyone who
can reach it can read your library through it. [Operate and configure](https://sam-dumont.github.io/immich-memories/docs/run/overview)
covers login, NAS/Kubernetes setup, backups and storage. Keep one UI replica.
Report vulnerabilities as [SECURITY.md](SECURITY.md) describes.

This is an independent companion to Immich, not made or endorsed by the Immich team.

## People and calendars

Families, relationships and calendars differ a lot, and this doesn't cover them all.
If yours is missing, say so. [Calendar limits](https://sam-dumont.github.io/immich-memories/docs/reference/film-types#holiday)
and [contributing household examples](https://sam-dumont.github.io/immich-memories/docs/contribute/development-setup#households-and-cultures)
show where help is useful.

## Development

Claude and Codex write most of the code; I set the direction and test films on a real library.
`make dev` installs the development tools and `make ci` runs the checks.
[CONTRIBUTING.md](CONTRIBUTING.md) describes the process;
[DISCLAIMER.md](DISCLAIMER.md) describes its limits.

## License

MIT, see [LICENSE](LICENSE).
