Welcome!‎ > ‎

Scripting Phoshare

Running the Phoshare Application

Phoshare can be run both as a Mac OSX application and a command line tool. The later mode allows you to embed phoshare into your own scripts, or launch it automatically as a scheduled job. The application is inside the Phoshare.app package. If you dragged it to your Application folder, the full path will be:

To run the script, open a Terminal session (from Applications->Utility), and change to the Phoshare MacOS folder:

$ cd /Applications/Phoshare.app/Contents/MacOS

Then you can run Phosare simply by typing:

$ ./Phoshare

Without any options, it launches as an application. If you use one or more options, it runs as a common line tool. To see a list of all available options, type:

$ ./Phoshare --help

iPhoto Library location

The first thing to do is locating your iPhoto library. By default, it will be at ~/Pictures/iPhoto\ Library. If you are not sure, quit iPhoto. Then hold down the Option key, and click on the iPhoto icon in the dock to relaunch it. It will come up with a dialog that prompts you for a library. Below the list of libraries it shows the path to the library. If you are using the default location, you don't need to tell Phoshare about it. If your library is not in the default location, use the --iphoto flag to tell phoshare.py.. For example, to export all your iPhoto events into ~/Pictures/Album from your default iPhoto library:

% ./Phoshare -e . --export ~/Pictures/Album
To use an iPhoto library from a different location:
% ./Phoshare -e . --iphoto ~/Pictures/MyLibrary --export ~/Pictures/Album

How to use Phoshare

I recommend you start out with a new folder for your export, like ~/Pictures/Album. You can run your first export like this:

./Phoshare -e . --iphoto "~/Pictures/iPhoto Library" --export ~/Pictures/Album

Please note the quotes around the iPhoto library location. They are required because there is a space in the folder name. If your iPhoto library is in the default location, you don't have to specify it on the command line, and you can just run:
./Phoshare -e . --export ~/Pictures/Album

This will export all events (-e .) from your iPhoto library at ~/Pictures/iPhoto Library. If you also want to include some of your albums or smart albums, use the -a and the -s options:
  ./Phoshare -e . -s "Last Import" -a "Vacation|Family" --iphoto "~/Pictures/iPhoto Library" --export ~/Pictures/Album
The arguments to the -e, -s, and -a are regular expressions that match the beginning of the event and album and album folder names. A . is a wildchard for any character, so -e . will match any event with at least one character in it's name. The | means "or", so -a "Vacation|Family" matches any album that starts with the word Vacation or Family, or any album that is contained in a folder that starts with the word Vacation or Family. If you want to get just Vacation, but not Vacation Last Year, change it to -a "Vacation$". The ^ and $ characters mark the beginning and end of the name. so Vacation$ only matches album names that match "Vacation" exactly. For more details on regular expressions, read the linked Wikipedia article. 

Sometimes you just want to skip a few albums or events. Instead of listing all the ones you want to export, you can use the -x option to exclude a few:

./Phoshare -e . -x "Bad Event|Another bad one" --iphoto "~/Pictures/iPhoto Library" --export ~/Pictures/Album

This will export all events except any event that starts with either "Bad Event" or "Another bad one".

Phoshare will create a folder for each event or album that matches. Within each folder, the image titles will be used as file names. If there are duplicates, a numeric suffix will be added. 

If you don't want all your 300 events turn into 300 folders in your export folder, you can assign a sub-folder name to events by adding a line starting with a @ in the folder description in iPhoto. For example, all events with the line @Vacation in their event description will be exported into ~/Pictures/Album/Vacation. You can have other text in the event description - phoshare only looks for lines starting with an @ character. Use the --folderhints option to scan event and album descriptions for folder hints:

./Phoshare -e . --folderhints --iphoto "~/Pictures/iPhoto Library" --export ~/Pictures/Album

Use the -k flag to have phoshare apply iPhoto image descriptions, dates, ratings, and keywords to the images:

./Phoshare -e . -k --iphoto "~/Pictures/iPhoto Library" --export ~/Pictures/Album

phoshare checks the descriptions and keywords only for new or updated images. So if you change the keywords later, phoshare will not export the change if you use -k. You can use -K instead, to check all images. There's really no drawback to doing that except that phoshare will run much longer because it has to open each image file to check it's existing meta data:

./Phoshare -e . -K --iphoto "~/Pictures/iPhoto Library" --export ~/Pictures/Album

If you are using iPhoto '09, you can ask phoshare to merge your face tags with the keywords, using the -f option (you need to combine it with either -k or -K to write the keywords):

./Phoshare -e . -k -f --iphoto "~/Pictures/iPhoto Library" --export ~/Pictures/Album

If you are using iPhoto '09, you can ask phoshare to export the GPS coordinates, using the -gps option (you need to combine it with either -k or -K to write the keywords):

./Phoshare -e . -k --gps --iphoto "~/Pictures/iPhoto Library" --export ~/Pictures/Album

You can also include place names (country, state, and city, and custom place names) with the -places option (you need to combine it with either -k or -K to write the keywords):

./Phoshare  -e . -k --gps --places --iphoto "~/Pictures/iPhoto Library" --export ~/Pictures/Album

If you have edited your pictures in iPhoto, phoshare will export the current, modified version of each picture. To also include the original images, use the -o option. The original image files will be exported into subfolders called Originals for each event and album:

./Phoshare -e . -k -f -o --iphoto "~/Pictures/iPhoto Library" --export ~/Pictures/Album

So far, we are only exporting new pictures. If phoshare finds an existing file or folder in your export folder that needs to be updated or should be deleted because it is not part of your iPhoto library, it just prints a warning. To enable full synchronization, use the -u (update) and -d (delete) flags:

./Phoshare -e . -k -f -o -d -u --iphoto "~/Pictures/iPhoto Library" --export ~/Pictures/Album

Be careful with this mode, because phoshare will overwrite any changes you made in your export folder, and delete any files that it thinks don't belong there! Better run without -d at first, and look at it's output, to see which files it would delete! So don't edit your pictures in the export folder, and don't add other images!

phoshare can resize images on export to fit into a given width and height. This option also converts all images to JPEG format, and re-compresses them at default quality, using the Core Image framework built into Mac OSX. I use this option to make a folder of images to sync with my Apple TV. That can save a lot of space on the Apple TV disk - there's no point to copy your original 10 Megapixel camera images to the Apple TV:

./Phoshare -e . -d -u --size 1920 --iphoto "~/Pictures/iPhoto Library" --export ~/Pictures/AppleTV

This will resize your images to fit into 1920x1920. Images smaller than that will not be enlarged.

Finally, if you are exporting to a folder on the same drive as your iPhoto library, you can use link mode, to create an export tree that uses very little disk space:

./Phoshare -e . -k -f -o -d -u -l --iphoto "~/Pictures/iPhoto Library" --export ~/Pictures/Album

If you just want to see what phoshare would do, add the --dryrun option to any of the command above. In that mode, no files will be modified!

If you use decide to keep using phoshare, you might want to create a little shell script to run it with the proper options. For example, I have a script make_album.sh that I run every time I want to synchronize my iPhoto library. It maintains both a linked tree in my ~/Pictures folder with both the modified and original images, and a second copy without the large movie files on a network drive:

LIBRARY="~/Pictures/iPhoto Library"
Phoshare -e . -s "Last Month|Previous Month|Cooking Collection" -k -o -d -u -f -l --iphoto "$LIBRARY" --export ~/Pictures/Album
Phoshare -e . -s "Last Month|Previous Month|Cooking Collection" -k -d -u -f --pictures --iphoto "$LIBRARY" --export /Volumes/Share/Pictures/Album

Use ./Phoshare --help to get a full listing of all options, with explanations.

Templates for Folders Names, File Names, and Image Captions

Templates are strings with place holders for values. The place holders have the format "{name}". Everything else in the template will be copied. Examples:

  • {title}
  • {yyyy}/{mm}/{dd} {title} - generates "2010/12/31 My Birthday" if the date of the pictures is Dec 31, 2010, and the title is "My Birthday".
  • {yyyy} Event: {event} - generates "2010 Event: Birthday" for an event with any date in 2010 and the name "Birthday".
 Item Command line option     Default value
 Folders --foldertemplate {name}
 Files --nametemplate {title}
 Image captions --captiontemplate {description}

Available place holders for folder names (--foldertemplate):
  • {name} - name of the album or event. This is the default.
  • {ascii_name} - name of the album or event, using only ASCII characters.
  • {plain_name} - name of the album or event, using only ASCII characters, and no spaces.
  • {hint} - folder hint (taken from line event or album description starting with @).
  • {yyyy} - year of album or event date.
  • {mm} - month of album or event date.
  • {dd} - date of album or event date.
Available place holders for file names (--nametemplate):
  • {album} - name of album (or in the case of an event, the name of the event).
  • {ascii_album} - name of album, using only ASCII characters.
  • {plain_album} - name of album, using only ASCII characters, and no spaces.
  • {index} - number of image in album, starting at 1.
  • {index0} - number of image in album, padded with 0s, so that all numbers have the same length.
  • {event} - name of the event. In the case of an album, the name of the event to which the image belongs.
  • {ascii_event} - name of the event, using only ASCII characters.
  • {plain_event} - name of the event, using only ASCII characters, and no spaces.
  • {event_index} - number of image in the event, starting at 1. If the case of an album, this number will be based on the event to which the image belongs.
  • {event_index0} - same as {event_index}, but padded with leading 0s so that all values have the same length.
  • {title} - image title. This is the default.
  • {ascii_title} - image title, using only ASCII characters.
  • {plain_title} - image title, using only ASCII characters, and no spaces.
  • {yyyy} - year of image.
  • {mm} - month of image (01 - 12).
  • {dd} - day of image (01 - 31).
If you are using {album}/{index}/{index0} place holders, the image will be named based on whatever album or event it is contained. That means an image in two albums will be exported with different names, even so the files are identical. If you want to use the same name for each image, regardless of which album it is in, use {event}, {event_index}, and {event_index0} instead.

Available place holders for captions (--captiontemplate):
  • {title} - image title.
  • {description} - image description. This is the default.
  • {title_description} - concatenated image title and description, separated by a : if both are set.
  • {yyyy} - year of image.
  • {mm} - month of image (01 - 12).
  • {dd} - day of image (01 - 31).
The defaults are the equivalent of calling Phoshare like this:
./Phoshare --foldertemplate "{name}" --nametemplate "{title}" --captiontemplate "{description}" ...