diff --git a/README.md b/README.md index 3534f05..8077cbe 100644 --- a/README.md +++ b/README.md @@ -1,52 +1,107 @@ -# Immich Selfie Timelapse Tool +# Immich Selfie Timelapse -This tool helps create selfie timelapses from your Immich instance. -It uses the powerful machine learning features of Immich to gather all the photographs where a particular individual appears, retrieves the bounding box metadata, and automatically crops and aligns the photos. +***Generate timelapse videos of your loved ones' portraits from your [Immich](https://immich.app/) 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.

- Example Image + Main View

- Example GIF + Timelapse example

- ## Features -- Automatically fetch images featuring a specified individual from your Immich instance. -- Extract bounding box metadata and crop/align photos using machine learning. -- Discard photos with low resolution (set by threshold). -- Discard photos where the subject is viewed from the side. -- Adds timestamp in the filename for easy chronological ordering. +- **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 -## Docker compose setup +

+ Processing +

-```yml +## 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: +- server.about +- asset.download +- asset.read +- person.read + +*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) + +```yaml services: immich-selfie-timelapse: image: arnaudcayrol/immich-selfie-timelapse container_name: immich-selfie-timelapse ports: - "5000:5000" - volumes: - - ./immich_selfie_timelapse:/app/output environment: - IMMICH_API_KEY=abcdefghijklmnopqrstuvwxyz - - IMMICH_BASE_URL=http://192.168.1.94:2283/api + - IMMICH_BASE_URL=http://your-immich-host:2283 + volumes: + - ./config:/app/config + - ./output:/app/output + restart: unless-stopped ``` -Once the service is started, access the webpage to configure the tool: http://127.0.0.1:5000. +### Docker Run + +```bash +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 + +| Path | Description | +|---|---| +| `/app/config` | Persisted configuration file (`config.toml`) | +| `/app/output` | Processed images and compiled timelapse video | + +### 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.

- Example GIF + Settings

-## Additional Notes +## Additional info + +- 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 GitHub stars ! -- For best looking results, I still recommand a manual pass over the final image folder to remove some outliers. The face orientation detection is not perfect at all. Hopefully someday I can get a better results. -- Contributions and improvements are welcome. ## License -This project is open source and available under the MIT License. \ No newline at end of file +This project is open source and available under the [MIT License](LICENSE). diff --git a/resources/example.jpg b/resources/example.jpg deleted file mode 100644 index c60034d..0000000 Binary files a/resources/example.jpg and /dev/null differ diff --git a/resources/example_gif.gif b/resources/example_gif.gif deleted file mode 100644 index ceb8748..0000000 Binary files a/resources/example_gif.gif and /dev/null differ diff --git a/resources/main_view.png b/resources/main_view.png new file mode 100644 index 0000000..9048f2d Binary files /dev/null and b/resources/main_view.png differ diff --git a/resources/processing_detail.png b/resources/processing_detail.png new file mode 100644 index 0000000..6531199 Binary files /dev/null and b/resources/processing_detail.png differ diff --git a/resources/result.gif b/resources/result.gif new file mode 100644 index 0000000..8f938a2 Binary files /dev/null and b/resources/result.gif differ diff --git a/resources/settings_details.png b/resources/settings_details.png new file mode 100644 index 0000000..05eb987 Binary files /dev/null and b/resources/settings_details.png differ diff --git a/resources/webpage.jpg b/resources/webpage.jpg deleted file mode 100644 index cb0334d..0000000 Binary files a/resources/webpage.jpg and /dev/null differ diff --git a/src/config.rs b/src/config.rs index aa6793a..39f5ad1 100644 --- a/src/config.rs +++ b/src/config.rs @@ -136,7 +136,7 @@ pub struct BrightnessConfig { impl Default for BrightnessConfig { fn default() -> Self { Self { - enabled: true, + enabled: false, min_brightness: 0.1, max_brightness: 0.9, } @@ -215,7 +215,7 @@ impl Default for OutputConfig { fn default() -> Self { Self { size: 512, - keep_intermediates: true, + keep_intermediates: false, } } } @@ -300,7 +300,7 @@ impl Default for EyeFilterConfig { fn default() -> Self { Self { enabled: true, - min_ear: 0.22, + min_ear: 0.12, } } }