Hello, I'm Elodie

~~ Your Personal EXIF-based Photo, Video and Audio Assistant ~~

Quickstart guide

Getting started takes just a few minutes.

Install ExifTool

Elodie relies on the great ExifTool library by Phil Harvey. You'll need to install it for your platform.

Some video features require version 10.20 or higher
Support for HEIC files requires version 11.50 or higher
Translating geolocation to city name requires version 13.13 or higher

Check your version by typing exiftool -ver and see the manual installation instructions for ExifTool if needed.

# OSX (uses homebrew, http://brew.sh/)
brew install exiftool

# Debian / Ubuntu
apt-get install libimage-exiftool-perl

# Fedora / Redhat
dnf install perl-Image-ExifTool

# Windows users can install the binary
# http://www.sno.phy.queensu.ca/~phil/exiftool/install.html

Clone the Elodie repository

You can clone Elodie from GitHub. You'll need git installed (instructions).

git clone https://github.com/jmathai/elodie.git
cd elodie
pip install -r requirements.txt

Give Elodie a test drive

Now that you've got the minimum dependencies installed you can start using Elodie. You'll need a photo, video or audio file and a folder you'd like Elodie to organize them into.

# Run these commands from the root of the repository you just cloned.
./elodie.py import --debug --destination="/where/i/want/my/photos/to/go" /where/my/photo/is.jpg

Testing changes safely with dry-run mode

Before running any command that modifies your photos, you can use the --dry-run flag to see exactly what Elodie would do without actually making any changes. This is especially useful when organizing large photo collections for the first time.

# See what would happen during import without actually copying files
./elodie.py import --dry-run --destination="/where/i/want/my/photos/to/go" /where/my/photos/are

# See what EXIF changes would be made without modifying files  
./elodie.py update --dry-run --location="Las Vegas, NV" /path/to/photo.jpg

# See what plugin operations would run without executing them
./elodie.py batch --dry-run

The dry-run mode shows you detailed output of what operations would be performed, letting you verify the organization structure and catch any issues before making actual changes to your photo library.

Now you're ready to learn more about Elodie.

Slowstart guide

Read a 3 part blog post on why I was created and how I can be used with Immich.

I work tirelessly to make sure your photos are always sorted and organized so you can focus on more important things. By photos I mean JPEG, DNG, NEF and common video and audio files.

You don't love me yet but you will.

I only do 3 things.

Firstly I organize your existing collection of photos into a customizable folder structure.
Second I help make it easy for all the photos you haven't taken yet to flow into the exact location they belong.
Third but not least I promise to do all this without a yucky propietary database that some friends of mine use.

NOTE: make sure you've installed everything I need before running the commands below. Instructions at the top of this page.

Let's organize your existing photos

My guess is you've got quite a few photos scattered around. The first thing I'll help you do is to get those photos organized. It doesn't matter if you have hundreds, thousands or tens of thousands of photos; the more the merrier.

Fire up your terminal and run this command which copies your photos into something a bit more structured.

./elodie.py import --destination="/where/i/want/my/photos/to/go" /where/my/photos/are

I'm pretty fast but depending on how many photos you have you might want to grab a snack. When you run this command I'll print out my work as I go along. If you're bored you can open /where/i/want/my/photos/to/go in Finder and watch as I effortlessly copy your photos there.

You'll notice that your photos are now organized by date and location. Some photos do not have proper dates or location information in them. I do my best and in the worst case scenario I'll use the earlier of the files access or modified time. Ideally your photos have dates and location in the EXIF so my work is more accurate.

Don't fret if your photos don't have much EXIF information. I'll show you how you can fix them up later on but let's walk before we run.

Back to your photos. When I'm done you should see something like this. Notice that I've renamed your files by adding the date and time they were taken. This helps keep them in chronological order when using most viewing applications. You'll thank me later.

├── 2015-06-Jun
│   ├── California
│   │   ├── 2015-06-29_16-34-14-img_3900.jpg
│   │   └── 2015-06-29_17-07-06-img_3901.jpg
│   └── Paris
│       └── 2015-06-30_02-40-43-img_3903.jpg
├── 2015-07-Jul
│   ├── Mountain View
│   │   ├── 2015-07-19_17-16-37-img_9426.jpg
│   │   └── 2015-07-24_19-06-33-img_9432.jpg
└── 2015-09-Sep
│   ├── Unknown Location
    │   ├── 2015-09-27_01-41-38-_dsc8705.dng
    │   └── 2015-09-27_01-41-38-_dsc8705.nef

Not too bad, eh? Wait a second, what's Unknown Location? If I'm not able to figure out where a photo was taken I'll place it into a folder named Unknown Location. This typically happens when photos do not have GPS information in their EXIF. You shouldn't see this for photos taken on a smartphone but it's often the case with digital cameras and SLRs.

Important: If you're importing photos that are missing location or time information in their EXIF, you can specify these during import using --location and --time options. Note that --location will overwrite any existing location data and --time will overwrite any existing time data, so only use them when the photos lack this information or when you know the existing EXIF data is incorrect.

# For photos missing location data
./elodie.py import --destination="/where/i/want/my/photos/to/go" --location="Las Vegas, NV" /where/my/photos/are

# For photos with incorrect or missing timestamps
./elodie.py import --destination="/where/i/want/my/photos/to/go" --time="2015-06-29 16:30:00" /where/my/photos/are

Alternatively, I can help you add GPS information to those photos after importing and get them organized better. Let me show you how.

Usage Instructions

You can view these instructions on the command line by typing ./elodie.py import --help, ./elodie.py update --help or ./elodie.py generate-db --help.

Import photos

Usage: elodie.py import [OPTIONS] [PATHS]...

  Import files or directories by reading their EXIF and organizing them
  accordingly.

Options:
  --destination DIRECTORY  Copy imported files into this directory.
                           [required]
  --source DIRECTORY       Import files from this directory, if specified.
  --file PATH              Import this file, if specified.
  --album-from-folder      Use images' folders as their album names.
  --trash                  After copying files, move the old files to the
                           trash.
  --allow-duplicates       Import the file even if it's already been imported.
  --location TEXT          Update the image location. Location should be the
                           name of a place, like "Las Vegas, NV".
  --time TEXT              Update the image time. Time should be in YYYY-mm-dd
                           hh:ii:ss or YYYY-mm-dd format.
  --debug                  Show more verbose debug output.
  --dry-run                Show what would be done without making any changes.
  --exclude-regex TEXT     Regular expression for directories or files to
                           exclude.
  --help                   Show this message and exit.

Update photos

Usage: elodie.py update [OPTIONS] FILES...

  Update a file's EXIF. Automatically modifies the file's location and file
  name accordingly.

Options:
  --album TEXT     Update the image album.
  --location TEXT  Update the image location. Location should be the name of a
                   place, like "Las Vegas, NV".
  --time TEXT      Update the image time. Time should be in YYYY-mm-dd
                   hh:ii:ss or YYYY-mm-dd format.
  --title TEXT     Update the image title.
  --debug          Show more verbose debug output.
  --dry-run        Show what would be done without making any changes.
  --help           Show this message and exit.

(Re)Generate checksum database

Usage: elodie.py generate-db [OPTIONS]

  Regenerate the hash.json database which contains all of the sha256
  signatures of media files. The hash.json file is located at ~/.elodie/.

Options:
  --source DIRECTORY  Source of your photo library.  [required]
  --help              Show this message and exit.

Run batch operations for all plugins

Usage: elodie.py batch [OPTIONS]

  Run batch() for

Elodie

Install / Use

README