Metadata-Version: 2.4
Name: immich-motion-deduplicator
Version: 0.1.0
Summary: Find and remove duplicated motion video assets in Immich
Project-URL: Homepage, https://github.com/itsWavs/Immich-motion-deduplicator
Project-URL: Issues, https://github.com/itsWavs/Immich-motion-deduplicator/issues
Project-URL: Repository, https://github.com/itsWavs/Immich-motion-deduplicator
License: MIT License
        
        Copyright (c) 2026 itsWavs
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: cli,deduplication,google-takeout,immich,photos
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
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.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Requires-Dist: requests>=2.32.5
Requires-Dist: rich>=14.2.0
Provides-Extra: dev
Requires-Dist: build>=1.2.2; extra == 'dev'
Requires-Dist: pytest>=8.4.2; extra == 'dev'
Description-Content-Type: text/markdown

# Immich Motion Deduplicator

`immich-motion-deduplicator` finds MP4 motion-video duplicates created by Google Takeout style exports and removes the standalone video assets from Immich.

It is designed as a one-off CLI tool:
- `scan` finds photo/video pairs with the same basename
- `ids` resolves matching Immich asset IDs through the API
- `delete` removes the matched video assets in batches
- `all` runs the full workflow end-to-end

## Why This Exists

Some exports contain both:
- a photo file such as `.jpg` or `.heic`
- a separate `.mp4` file containing only the motion portion

After import, Immich can show both as separate assets. This tool helps clean up the duplicate motion videos while keeping the still image.

## Requirements

- Python 3.9+
- network access to your Immich API
- an Immich API key with permission to delete assets

## Install

### pipx

```bash
pipx install immich-motion-deduplicator
```

### uv

```bash
uv tool install immich-motion-deduplicator
```

### pip

```bash
pip install immich-motion-deduplicator
```

### From Source

```bash
git clone https://github.com/itsWavs/Immich-motion-deduplicator.git
cd Immich-motion-deduplicator
pip install .
```

## Configuration

The app reads configuration from environment variables. If a `.env` file exists in the current working directory, it is loaded automatically.

Copy `.env.example` to `.env` and fill in your values:

```env
IMMICH_ROOT_DIR=/path/to/your/immich/library
IMMICH_API_URL=http://your-immich-host:2283/api
IMMICH_API_KEY=your_api_key
MOTION_CANDIDATES_CSV=motion_candidates.csv
MOTION_CANDIDATES_WITH_IDS_CSV=motion_candidates_with_ids.csv
```

Notes:
- `IMMICH_API_URL` may include `/api` or omit it
- CSV paths may be relative to the current working directory
- for Docker, `IMMICH_ROOT_DIR` must use the container-mounted path, not the host path

## Usage

Installed command:

```bash
immich-motion-deduplicator scan
immich-motion-deduplicator ids
immich-motion-deduplicator delete
immich-motion-deduplicator all --dry-run
immich-motion-deduplicator all
```

Module form:

```bash
python -m immich_motion_deduplicator scan
python -m immich_motion_deduplicator ids
python -m immich_motion_deduplicator delete
python -m immich_motion_deduplicator all --dry-run
python -m immich_motion_deduplicator all
```

Behavior:
- `delete` is safe by default and only deletes when you add `--execute`
- `all` deletes by default so it works cleanly in automation
- `all --dry-run` previews the full workflow without deleting anything

Recommended flow:

```bash
immich-motion-deduplicator all --dry-run
immich-motion-deduplicator all
```

## Docker

Docker is useful as an optional distribution path for one-off runs and automation. The repository includes a `Dockerfile` and `docker-compose.example.yml`.

Build the image:

```bash
docker build -t immich-motion-deduplicator .
```

Run it:

```bash
docker run --rm \
  --env-file .env \
  -v /path/to/your/immich/library:/library:ro \
  -v "$PWD":/work \
  -w /work \
  immich-motion-deduplicator all --dry-run
```

When running in Docker, set `IMMICH_ROOT_DIR=/library` inside `.env` or pass it explicitly as an environment variable.

## Development

Install the project with test dependencies:

```bash
pip install -e ".[dev]"
pytest
python -m build
```

## Safety

- review the dry-run output before deleting
- keep backups of your library and database before bulk deletion tools
- this tool deletes Immich assets through the API and does not modify files directly on disk
