Metadata-Version: 2.5
Name: immich-memories
Version: 1.0.0-rc.8
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 finished MP4 memory
films. Pick a month, a year, a trip, an album or a person. It reads Immich's dates, favourites,
people and places, groups pictures into moments and proposes a cut in time order, with the
reason each shot is there. You review it, swap what you don't like, then render with titles and
music. A quiet month makes a short film rather than 3 minutes of filler.

It runs on a plain NAS with no GPU and no model. A GPU or a model makes it better.

<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> · CC0 stock pictures, <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>

The first link is a demo of the app, the second a finished trip film. Both use
CC0 stock pictures, never anyone's family.

## What you can do

- **Photos and videos in one film.** Stills get animated, videos give their best few seconds,
  Live Photos keep their motion. Favourites and named people win close calls, and you can see
  everything that was left in the pool.
- **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.** Bundled tracks and template titles work on day one.
  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 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).

## Make your first film

The default is **one prebuilt Docker container** next to your existing Immich. No GPU, no hosted
model account, no caption server. You need Docker Compose v2, two CPU cores, **4 GiB RAM for
this app on top of Immich**, and **25 GB for app data, images and finished films**. Immich v2 and
v3 both work; [the deployment matrix](https://sam-dumont.github.io/immich-memories/docs/run/tested-deployments)
says which versions and setups were actually tested.

The first run downloads the image and model files, then prepares the pictures you pick. A full
month can take hours on a NAS, so start with **20–50 photos/videos and a 30-second film**. A short
film alone doesn't shrink the preparation: pick a short period too.
[Progress and recovery](https://sam-dumont.github.io/immich-memories/docs/get-started/first-film#progress-and-recovery)
shows each phase and where to look when it stops.

Follow the [quick start](https://sam-dumont.github.io/immich-memories/docs/get-started/quick-start),
then [Your first film](https://sam-dumont.github.io/immich-memories/docs/get-started/first-film).
Use the docs that match your release: a development preview says so when its downloads don't
exist yet. Upload stays off on the first run, and you end with a local file you can play.

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