Immich Selfie Timelapse

Generate timelapse videos of your loved ones' portraits from your Immich photo library.

Use Immich's built-in face recognition to find all photos of a person, then runs them through a configurable processing pipeline that crops, aligns, filters, and compiles the results into a smooth timelapse video.

Features

• Face detection & cropping - Uses Immich's face recognition metadata to locate and crop faces automatically
• Face alignment - Aligns all photos based on eye positions for a stable, smooth timelapse
• Head pose filtering - Skips non-front-facing photos using an ONNX deep learning model (DMHead)
• Blink detection - Filters out photos where eyes are closed using Eye Aspect Ratio analysis
• Blur detection - Discards blurry photos using gradient magnitude analysis (Sobel operator)
• Brightness filtering - Removes photos that are too dark or overexposed
• Face resolution filtering - Skips photos where the face is too small
• Photo limiting - Caps photos per day/week/month to avoid over-representing busy periods
• Timestamp overlay - Optionally overlays the date on each frame
• Video compilation - Automatically compiles processed photos into an MP4 timelapse using FFmpeg
• Web UI - Configure all settings and monitor progress through a built-in web interface

Quick Start

Immich API key

To access your immich library, this project requires an Immich API key.
Follow this guide to create one: https://immich.app/docs/features/command-line-interface#obtain-the-api-key

Here are the features that need to be enabled: - album.read - asset.download - asset.read - asset.view - person.read - server.about

Note: It is advised to store this API key in a .env file adjacent to your docker-compose.yml rather than in plain text.

Docker Compose (recommended)

services:
  immich-selfie-timelapse:
    image: arnaudcayrol/immich-selfie-timelapse
    container_name: immich-selfie-timelapse
    user: 1000:1000
    ports:
      - "5000:5000"
    environment:
      - IMMICH_API_KEY=abcdefghijklmnopqrstuvwxyz
      - IMMICH_BASE_URL=http://your-immich-host:2283
    volumes:
      - ./config:/app/config
      - ./output:/app/output
    restart: unless-stopped

Docker Run

docker run -d \
  --name immich-selfie-timelapse \
  -p 5000:5000 \
  -e IMMICH_API_KEY=your-api-key-here \
  -e IMMICH_BASE_URL=http://your_server:2283 \
  -v ./config:/app/config \
  -v ./output:/app/output \
  arnaudcayrol/immich-selfie-timelapse

Then open http://your_server:5000 to access the web interface.

Volumes

Ensure correct read/write permissions to the config and output folders.

chown -R 1000:1000 ./config ./output

Settings

The default settings are quite permissive because every human being is unique.
Please adjust image brightness filtering, eye aspect ratio etc. for the person you are processing.

Troubleshoot

• No ARM support yet.
• Processor must support AVX (DMHead model requirement).

Additional info

• The photo filtering is not 100% accurate and will continue to improve.
• Heartfelt thanks to the Immich team and contributors for making this project possible.
• About contribution : When I first created this project, I marked it as open to contributions. I now realize that I don't have as much time as I thought to dedicate to this project. I feel comfortable with issues being opened as it allows me to go through them at my own pace. For pull requests, I cannot guarantee a reasonable time frame for review.
• Thank you thomaslrg for the discussions around the project.
• Thank you for the ~~200~~ 300 GitHub stars !

License

This project is open source and available under the MIT License.

Star History