= MiniExiftool

This library is wrapper for the Exiftool command-line application
(http://www.sno.phy.queensu.ca/~phil/exiftool) written by Phil Harvey.
Read and write access is done in a clean OO manner.

== Requirements

Ruby 1.9 or higher and an installation of the Exiftool
command-line application at least version 7.65.
If you run on Ruby 1.8 or with a prior exiftool version
install mini_exiftool version 1.x.x.
Instructions for installation you can find under
http://www.sno.phy.queensu.ca/~phil/exiftool/install.html .

Alternatively Wil Gieseler has bundled a meta-gem that eliminates the
need for a separate Exiftool installation. Have a look at
http://github.com/wilg/mini_exiftool_vendored or
http://rubygems.org/gems/mini_exiftool_vendored .

== Installation

First you need Exiftool (see under Requirements above). Then you can simply
install the gem with
 gem install mini_exiftool

If you need to support older versions of Ruby or exiftool (see Requirements above)
  gem install --version "< 2.0.0" mini_exiftool

== Configuration

You can manually set the exiftool command that should be used via
  MiniExiftool.command = '/path/to/my/exiftool'

In addition, you can also tell MiniExiftool where to store the PStore files with tags
which exiftool supports. The PStore files are used for performance issues.
Per default the PStore files are stored in a sub directory .mini_exiftool or
_mini_exiftool under your home directory.
  MiniExiftool.pstore_dir = '/path/to/pstore/dir'

If you're using Rails, this is easily done with
  MiniExiftool.pstore_dir = Rails.root.join('tmp').to_s

Important hint: if you have to change the configuration you have to do this direct
after require 'mini_exiftool'.

== Usage

In general MiniExiftool is very intuitive to use as the following examples show:

 # Reading meta data from a file
 photo = MiniExiftool.new 'photo.jpg'
 puts photo.title

 # Alternative reading meta data from an IO instance
 photo = MiniExiftool.new io
 puts photo.title

 # Writing meta data
 photo = MiniExiftool.new 'photo.jpg'
 photo.title = 'This is the new title'
 photo.save

 # Copying meta data
 photo = MiniExiftool.new('photo.jpg')
 photo.copy_tags_from('another_photo.jpg', :author)


For further information about using MiniExiftool read the Tutorial.rdoc
in the project root folder and have a look at the examples in directory
examples.

== Encodings

In MiniExiftool all strings are encoded in UTF-8. If you need other
encodings in your project use the String#encod* methods.

If you have problems with corrupted strings when using MiniExiftool
there are two reasons for this:

=== Internal character sets

You can specify the charset in which the meta data is in the file encoded
if you read or write to some sections of meta data (i.e. IPTC, XMP ...).
It exists various options of the form *_encoding: exif, iptc, xmp, png,
id3, pdf, photoshop, quicktime, aiff, mie and vorbis.

For IPTC meta data it is recommended to set also the CodedCharacterSet
tag.

Please read the section about the character sets of the ExifTool command
line application carefully to understand what's going on
(http://www.sno.phy.queensu.ca/~phil/exiftool/faq.html#Q10)!

 # Using UTF-8 as internal encoding for IPTC tags and MacRoman
 # as internal encoding for EXIF tags
 photo = MiniExiftool.new('photo.jpg', iptc_encoding: 'UTF8',
                          exif_encoding: 'MacRoman'
 # IPTC CaptionAbstract is already UTF-8 encoded
 puts photo.caption_abstract
 # EXIF Comment is converted from MacRoman to UTF-8
 puts photo.comment

 photo = MiniExiftool.new('photo.jpg', iptc_encoding: 'UTF8',
                          exif_encoding: 'MacRoman'
 # When saving IPTC data setting CodedCharacterSet as recommended
 photo.coded_character_set = 'UTF8'
 # IPTC CaptionAbstract will be stored in UTF-8 encoding
 photo.caption_abstract = 'Some text with Ümläuts'
 # EXIF Comment will be stored in MacRoman encoding
 photo.comment = 'Comment with Ümläuts'
 photo.save

=== Corrupt characters

You use the correct internal character set but in the string are still corrupt
characters.
This problem you can solve with the option replace_invalid_chars:

 # Replace all invalid characters with a question mark
 photo = MiniExiftool.new('photo.jpg', replace_invalid_chars: '?')

== Contribution

The code is hosted in a git repository on Gitorious at
http://gitorious.org/mini_exiftool
and github at
https://github.com/janfri/mini_exiftool
feel free to contribute!

== Author
Jan Friedrich <janfri26@gmail.com>

== Copyright / License
Copyright (c) 2007-2016 by Jan Friedrich

Licensed under terms of the GNU LESSER GENERAL PUBLIC LICENSE, Version 2.1,
February 1999 (see file COPYING for more details)
