exiftool-vendored.pl

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd"> <html> <head> <title>Image::ExifTool</title> <link rel=stylesheet type='text/css' href='style.css' title='Style'> <style type="text/css">  </style> </head> <body> <h1 class='up'>The Image::ExifTool Perl Library Module</h1> <h2>Description</h2> <p>The Image::ExifTool library provides a set of Perl modules to read and write meta information in a wide variety of image, audio, video and document files.</p> <hr><h2><a name="Methods">Methods</a></h2> <p>All ExifTool features are accessed through the methods of the public interface listed below. Other Image::ExifTool methods and modules should not be accessed directly because their interface may change with future versions.</p> <p>The ExifTool methods should never die or issue a warning to STDERR if called with the proper arguments (with the exception of <a href="#SetNewValue">SetNewValue</a> which may send an error message to STDERR, but only when called in scalar context). Error and warning messages that occur during processing are stored in the values of the Error and Warning tags, and are accessible via the <a href="#GetValue">GetValue</a> method to retrieve a single Error or Warning message, or <a href="#GetInfo">GetInfo</a> to retrieve any number of them.</p> <p>The ExifTool methods are not thread safe.</p> <table><tr><td valign=top> <ul> <li><a href="#ImageInfo">ImageInfo</a></li> <li><a href="#new">new</a></li> <li><a href="#Options">Options</a></li> <li><a href="#ClearOptions">ClearOptions</a></li> <li><a href="#ExtractInfo">ExtractInfo</a></li> <li><a href="#GetInfo">GetInfo</a></li> <li><a href="#WriteInfo">WriteInfo</a></li> <li><a href="#GetTagList">GetTagList</a></li> <li><a href="#GetFoundTags">GetFoundTags</a></li> <li><a href="#GetRequestedTags">GetRequestedTags</a></li> <li><a href="#GetValue">GetValue</a></li> <li><a href="#SetNewValue">SetNewValue</a></li> </ul> </td><td valign=top> <ul> <li><a href="#GetNewValue">GetNewValue</a></li> <li><a href="#SetNewValuesFromFile">SetNewValuesFromFile</a></li> <li><a href="#CountNewValues">CountNewValues</a></li> <li><a href="#SaveNewValues">SaveNewValues</a></li> <li><a href="#RestoreNewValues">RestoreNewValues</a></li> <li><a href="#SetFileModifyDate">SetFileModifyDate</a></li> <li><a href="#SetFileName">SetFileName</a></li> <li><a href="#SetNewGroups">SetNewGroups</a></li> <li><a href="#GetNewGroups">GetNewGroups</a></li> <li><a href="#GetTagID">GetTagID</a></li> <li><a href="#GetDescription">GetDescription</a></li> <li><a href="#GetGroup">GetGroup</a></li> </ul> </td><td valign=top> <ul> <li><a href="#GetGroups">GetGroups</a></li> <li><a href="#BuildCompositeTags">BuildCompositeTags</a></li> <li><a href="#GetTagName">GetTagName</a></li> <li><a href="#GetShortcuts">GetShortcuts</a></li> <li><a href="#GetAllTags">GetAllTags</a></li> <li><a href="#GetWritableTags">GetWritableTags</a></li> <li><a href="#GetAllGroups">GetAllGroups</a></li> <li><a href="#GetDeleteGroups">GetDeleteGroups</a></li> <li><a href="#GetFileType">GetFileType</a></li> <li><a href="#CanWrite">CanWrite</a></li> <li><a href="#CanCreate">CanCreate</a></li> <li><a href="#AddUserDefinedTags">AddUserDefinedTags</a></li> </ul> </td></tr></table> <hr><h2><a name="UsingExifTool">Using ExifTool</a></h2> <p>The ExifTool module may be used by simply calling the <a href="#ImageInfo">ImageInfo</a> function:</p> <blockquote><table class='box'><tr><td><pre> use Image::ExifTool qw(:Public); my $info = <a href="#ImageInfo">ImageInfo</a>('image.jpg'); </pre></td></tr></table></blockquote> <p>or in a more object-oriented fashion, by creating an ExifTool object:</p> <blockquote><table class='box'><tr><td><pre> use Image::ExifTool; my $exifTool = <a href="#new">new</a> Image::ExifTool; my $info = $exifTool-><a href="#ImageInfo">ImageInfo</a>('image.jpg'); </pre></td></tr></table></blockquote> <p>The object-oriented method allows more flexibility, but is slightly more complicated. You choose the method that you prefer.</p> <p>The $info value returned by <a href="#ImageInfo">ImageInfo</a> in the above examples is a reference to a hash containing the tag/value pairs. Here is a simplified example which prints out this information:</p> <blockquote><table class='box'><tr><td><pre> foreach (keys %$info) { print "$_ => $$info{$_}\n"; } </pre></td></tr></table></blockquote> <p>See <a href="#ImageInfo">ImageInfo</a> for a more detailed description of the info hash entries.</p> <p>And the technique for writing meta information is equally simple:</p> <blockquote><table class='box'><tr><td><pre> use Image::ExifTool; my $exifTool = <a href="#new">new</a> Image::ExifTool; $exifTool-><a href="#SetNewValue">SetNewValue</a>(Author => 'Phil Harvey'); $exifTool-><a href="#WriteInfo">WriteInfo</a>('image.jpg','modified_image.jpg'); </pre></td></tr></table></blockquote> <hr><h2><a name="Config">Configuration</a></h2> <p>User-defined tags can be added via the ExifTool configuration file, or by defining the %Image::ExifTool::UserDefined hash before calling any ExifTool functions. See "<a href="config.html">ExifTool_config</a>" in the ExifTool distribution for more details.</p> <p>By default ExifTool looks for a configuration file named ".ExifTool_config" first in your home directory, then in the directory of the application script, but a different directory may be specified by setting the EXIFTOOL_HOME environment variable, or a different file may be specified by setting the ExifTool "<code>configFile</code>" variable before using Image::ExifTool. For example:</p> <blockquote><table class='box'><tr><td><pre> BEGIN { $Image::ExifTool::configFile = '/Users/phil/myconfig.cfg' } use Image::ExifTool; </pre></td></tr></table></blockquote> <p>The configuration feature may also be disabled by setting "<code>configFile</code>" to an empty string:</p> <blockquote><table class='box'><tr><td><pre> BEGIN { $Image::ExifTool::configFile = '' } use Image::ExifTool; </pre></td></tr></table></blockquote> <hr><h2><a name="ImageInfo">ImageInfo</a></h2> <p>Read image file and return meta information. This is the one-step function for retrieving meta information from an image. Internally, <a href="#ImageInfo">ImageInfo</a> calls <a href="#ExtractInfo">ExtractInfo</a> to extract data from the image, <a href="#GetInfo">GetInfo</a> to generate the information hash, and <a href="#GetTagList">GetTagList</a> for the returned tag list.</p> <blockquote><table class='norm'> <tr><td><b>Prototype</b></td><td>ImageInfo($;@)</td></tr> <tr><td valign=top><b>Inputs</b></td><td><b>0)</b> [<i>optional</i>] ExifTool object reference <br><b>1)</b> File name, file reference or scalar reference <br><b>2-N)</b> [<i>optional</i>] list of tag names to find (or tag list reference or options reference, see below) </td></tr> <tr><td valign=top><b>Returns</b></td><td>Reference to hash of tag key/value pairs</td></tr> </table></blockquote> <p><b>Examples:</b></p> <blockquote>Non object-oriented example showing use of options and returning tag list: <table class='box'><tr><td><pre> use Image::ExifTool qw(ImageInfo); my @ioTagList; my $info; $info = <b>ImageInfo</b>('image.jpg', \@ioTagList, {Sort => 'Group0'}); </pre></td></tr></table></blockquote> <blockquote>Object-oriented example to read from a file that is already open: <table class='box'><tr><td><pre> my $exifTool = <a href="#new">new</a> Image::ExifTool; $info = $exifTool-><b>ImageInfo</b>(\*FILE_PT, 'Aperture', 'ShutterSpeed', 'ISO'); </pre></td></tr></table></blockquote> <blockquote>Extract information from an image in memory: <table class='box'><tr><td><pre> $info = $exifTool-><b>ImageInfo</b>(\$imageData); </pre></td></tr></table></blockquote> <blockquote>Extract information from an embedded thumbnail image: <table class='box'><tr><td><pre> $info = <b>ImageInfo</b>('image.jpg', 'thumbnailimage'); my $thumbInfo = <b>ImageInfo</b>($$info{ThumbnailImage}); </pre></td></tr></table></blockquote> <blockquote>Using an ExifTool object to set the options before calling <a href="#ImageInfo">ImageInfo</a>: <table class='box'><tr><td><pre> my $filename = shift || die "Please specify filename\n"; my @ioTagList = qw(filename imagesize xmp:creator exif:* -ifd1:*); $exifTool-><a href="#Options">Options</a>(Unknown => 1, DateFormat => '%H:%M:%S %a. %b. %e, %Y'); $info = $exifTool-><b>ImageInfo</b>($filename, \@ioTagList); </pre></td></tr></table></blockquote> <p><b>Function Arguments:</b></p> <p><a href="#ImageInfo">ImageInfo</a> is very flexible about the arguments passed to it, and interprets them based on their type. It may be called with one or more arguments. The one required argument is either a SCALAR (the image file name), a file reference (a reference to the image file) or a SCALAR reference (a reference to the image in memory). Other arguments are optional. The order of the arguments is not significant, except that the first SCALAR is taken to be the file name unless a file reference or scalar reference comes earlier in the argument list.</p> <p>Below is a more detailed explanation of how the <a href="#ImageInfo">ImageInfo</a> function arguments are interpreted.</p> <blockquote><table class='norm'> <tr><td valign=top><b>ExifTool ref</b></td><td> <a href="#ImageInfo">ImageInfo</a> may be called with an ExifTool object if desired. Advantages of using the object-oriented form are that options may be set before calling <a href="#ImageInfo">ImageInfo</a>, and the object may be used afterward to access member functions. Must be the first argument if used. </td></tr><tr><td valign=top><b>SCALAR</b></td><td> The first scalar argument is taken to be the file name unless an earlier argument specified the image data via a file reference (file ref) or data reference (SCALAR ref). The remaining scalar arguments are names of tags for requested information. All tags are returned if no tags are specified. <br> <br> Tag names are case-insensitive and may be prefixed by optional group names separated by colons. A group name may begin with a family number (eg. '<code>1IPTC:Keywords</code>'), to restrict matches to a specific family. In the tag name, a '<code>?</code>' matches any single character and a '<code>*</code>' matches zero or more characters. Thus '<code>GROUP:*</code>' represents all tags in a specific group. Wildcards may not be used in group names, with the exception that a group name of '<code>*</code>' may be used to extract all available instances of a tag regardless of the <a href="#Duplicates">Duplicates</a> setting (eg. '<code>*:WhiteBalance</code>'). Multiple groups may be specified (eg. '<code>EXIF:Time:*</code>' extracts all EXIF Time tags). And finally, a leading '<code>-</code>' indicates a tag to be excluded (eg. '<code>-IFD1:*</code>'), or a trailing '<code>#</code>' causes the ValueConv value to be returned for this tag. <br> <br> Note that keys in the returned information hash and elements of the returned tag list are not necessarily the same as these tag names because group names are removed, the case may be changed, and an instance number may be added. For this reason it is best to use either the keys of the returned hash or the elements of the returned tag list when accessing the tag values. <br> <br> See the <a href="TagNames/index.html">TagNames</a> documentation for a complete list of ExifTool tag names. </td></tr><tr><td valign=top><b>File ref</b></td><td> A reference to an open image file. If you use this method (or a SCALAR reference) to access information in an image, the FileName and Directory tags will not be returned. (Also, the FileSize, FileModifyDate, FilePermissions and FileAttributes tags will not be returned unless it is a plain file.) Image processing begins at the current file position, and on return the file position is unspecified. May be either a standard filehandle or a reference to a File::RandomAccess object. <br> <br> [Advanced: To allow a non-rewindable stream (eg. a network socket) to be re-read after processing with ExifTool, first wrap the file reference in a File::RandomAccess object, then pass this object to <a href="#ImageInfo">ImageInfo</a>. The File::RandomAccess object will buffer the file if necessary, and may be used to re-read the file after <a href="#ImageInfo">ImageInfo</a> returns.] </td></tr><tr><td valign=top><b>SCALAR ref</b></td><td> A reference to image data in memory. </td></tr><tr><td valign=top><b>ARRAY ref</b></td><td> Reference to a list of tag names. On entry, any elements in the list are added to the list of requested tags. On return, this list is updated to contain an ordered list of tag keys for the returned information. <br> <br> There will be 1:1 correspondence between the requested tags and the returned tag keys only if the <a href="#Duplicates">Duplicates</a> option is 0 and <a href="#Sort">Sort</a> is 'Input'. (With <a href="#Duplicates">Duplicates</a> enabled, there may be more entries in the returned list of tag keys, and with other <a href="#Sort">Sort</a> settings the entries may not be in the same order as requested.) If a requested tag doesn't exist, a tag key is still generated, but the tag value is undefined. </td></tr><tr><td valign=top><b>HASH ref</b></td><td> Reference to a hash containing the options settings. See <a href="#Options">Options</a> documentation below for a list of available options. Options specified as arguments to <a href="#ImageInfo">ImageInfo</a> take precedence over <a href="#Options">Options</a> settings. </td></tr></table></blockquote> <p><b>Return Value:</b></p> <p><a href="#ImageInfo">ImageInfo</a> returns a reference to a hash of tag key/value pairs. The tag keys are identifiers, which are similar to the tag names but may have an appended instance number if multiple tags with the same name were extracted from the image. Many of the ExifTool functions require a tag key as an argument. Use <a href="#GetTagName">GetTagName</a> to get the tag name for a given tag key. Note that the case of the tag names may not be the same as requested.</p> <p>Values of the returned hash are usually simple scalars, but a scalar reference is used to indicate binary data and an array reference may be used to indicate a list. Also, a hash reference may be returned if the <a href="#Struct">Struct</a> option is used. Lists of values are joined by commas into a single string only if the PrintConv option is enabled and the List option is disabled (which are the defaults). Note that binary values are not necessarily extracted unless specifically requested, or the Binary option is enabled and the tag is not specifically excluded. If not extracted the value is a reference to a string of the form "<code>Binary data ##### bytes</code>".</p> <p>Here is a simple example to print out the information returned by <a href="#ImageInfo">ImageInfo</a>:</p> <blockquote><table class='box'><tr><td><pre> foreach (keys %$info) { my $val = $$info{$_}; if (ref $val eq 'ARRAY') { $val = join(', ', @$val); } elsif (ref $val eq 'SCALAR') { $val = '(Binary data)'; } printf("%-24s : %s\n", $_, $val); } </pre></td></tr></table></blockquote> <p>which gives output like this (PrintConv enabled):</p> <blockquote><table class='box'><tr><td><pre> WhiteBalance : Auto FNumber : 3.5 InteroperabilityOffset : 936 XResolution : 72 ISO : 100 ThumbnailImage : (Binary data) FlashOn : On Make : FUJIFILM ShutterSpeedValue : 1/64 ExposureCompensation : 0 Sharpness : Soft ResolutionUnit : inches </pre></td></tr></table></blockquote> <p><b>Notes:</b></p> <p>ExifTool returns all values as byte strings of encoded characters. Perl wide characters are not used. See <a href="faq.html#Q10">FAQ number 10</a> for details about the encodings. By default, most returned strings are encoded in UTF-8. For these, Encode::decode_utf8() may be used to convert to a sequence of logical Perl characters.</p> <p>As well as tags representing information extracted from the image, the following <a href="TagNames/Extra.html">Extra tags</a> generated by ExifTool may be returned:</p> <blockquote><table class='norm'> <tr><td><b>ExifToolVersion</b></td><td>The ExifTool version number</td></tr> <tr><td><b>Error</b></td><td>An error message if the image could not be processed</td></tr> <tr><td><b>Warning</b></td><td>A warning message if problems were encountered while processing the image</td></tr> </table></blockquote> <hr><h2><a name="new">new</a></h2> <p>Create a new ExifTool object.</p> <p><b>Example:</b></p> <blockquote><table class='box'><tr><td><pre> my $exifTool = <b>new</b> Image::ExifTool; </pre></td></tr></table></blockquote> <p>Note that ExifTool uses AUTOLOAD to load non-member methods, so any class using Image::ExifTool as a base class must define an AUTOLOAD which calls Image::ExifTool::DoAutoLoad(). ie)</p> <blockquote><table class='box'><tr><td><pre> sub AUTOLOAD { Image::ExifTool::DoAutoLoad($AUTOLOAD, @_); } </pre></td></tr></table></blockquote> <hr><table bgcolor='#aaffaa' width='100%' cellpadding=8><tr><td><center><b> The following functions require an ExifTool object as the first argument </b></center></td></tr></table> <hr><h2><a name='options'></a><a name="Options">Options</a></h2> <p>Get/set ExifTool options. This function can be called to set the default options for an ExifTool object. Options set this way are in effect for all function calls but may be overridden by options passed as arguments to some functions. Option names are not case sensitive.</p> <p>The default option values may be changed by defining a %Image::ExifTool::UserDefined::Options hash. See the <a href="config.html">ExifTool_config file</a> in the full ExifTool distribution for examples.</p> <blockquote><table class='norm'> <tr><td><b>Prototype</b></td><td>Options($$;@)</td></tr> <tr><td valign=top><b>Inputs</b></td><td><b>0)</b> ExifTool object reference <br><b>1)</b> Parameter name (case-insensitive, see table below) <br><b>2)</b> [<i>optional</i>] Option value if specified (may be undef to clear option) <br><b>3-N)</b> [<i>optional</i>] Additional parameter/value pairs </td></tr> <tr><td valign=top><b>Returns</b></td><td>Previous value of last specified parameter</td></tr> </table></blockquote> <p><b>Available options:</b></p> <blockquote> <table class='norm'> <tr><th colspan=4 bgcolor='#dddddd'><font size='+1'>ExifTool Options</font></th></tr> <tr><th>Option</th><th>Description</th><th>Values</th><th>Default</th></tr> <tr id="Binary"><td>Binary</td><td>Flag to extract the value data for all binary tags. Tag values representing large binary data blocks (eg. ThumbnailImage) are not necessarily extracted unless this option is set or the tag is specifically requested by name.</td> <td align=center>0 or 1</td><td align=center>undef</td></tr> <tr id="ByteOrder"><td>ByteOrder</td><td>The byte order for newly created EXIF segments when writing. Note that if EXIF information already exists, the existing order is maintained. If ByteOrder is not defined, then the order of the maker notes is used (if they are being copied), otherwise big-endian ('MM') order is assumed. This can also be set via the <a href="TagNames/Extra.html">ExifByteOrder tag</a>, but the ByteOrder option takes precedence if both are set.</td> <td align=center>'MM','II' or undef</td><td align=center>undef</td></tr> <tr id="Charset"><td>Charset</td><td>Character set for encoding character strings passed to/from ExifTool containing code points above U+007F. Note that this option affects some types of information when reading/writing the file and other types when getting/setting tag values, so it must be defined for both types of access. Charset values listed to the right have aliases which are given in brackets. Case is not significant. See <a href="faq.html#Q10">FAQ #10</a> for more information about character sets.</td> <td align=center><table class=clear> <tr><td valign=top align=right>UTF8</td><td>(cp65001, UTF-8)</td></tr> <tr><td valign=top align=right>Latin</td><td>(cp1252, Latin1)</td></tr> <tr><td valign=top align=right>Latin2</td><td>(cp1250)</td></tr> <tr><td valign=top align=right>Cyrillic</td><td>(cp1251, Russian)</td></tr> <tr><td valign=top align=right>Greek</td><td>(cp1253)</td></tr> <tr><td valign=top align=right>Turkish</td><td>(cp1254)</td></tr> <tr><td valign=top align=right>Hebrew</td><td>(cp1255)</td></tr> <tr><td valign=top align=right>Arabic</td><td>(cp1256)</td></tr> <tr><td valign=top align=right>Baltic</td><td>(cp1257)</td></tr> <tr><td valign=top align=right>Vietnam</td><td>(cp1258)</td></tr> <tr><td valign=top align=right>Thai</td><td>(cp874)</td></tr> <tr><td valign=top align=right>MacRoman</td><td>(cp10000, Mac, Roman)</td></tr> <tr><td valign=top align=right>MacLatin2</td><td>(cp10029)</td></tr> <tr><td valign=top align=right>MacCyrillic</td><td>(cp10007)</td></tr> <tr><td valign=top align=right>MacGreek</td><td>(cp10006)</td></tr> <tr><td valign=top align=right>MacTurkish</td><td>(cp10081)</td></tr> <tr><td valign=top align=right>MacRomanian</td><td>(cp10010)</td></tr> <tr><td valign=top align=right>MacIceland</td><td>(cp10079)</td></tr> <tr><td valign=top align=right>MacCroatian</td><td>(cp10082)</td></tr> </table></td><td align=center>'UTF8'</td></tr> <tr id="CharsetEXIF"><td>CharsetEXIF</td><td>Internal encoding to use for stored EXIF "ASCII" string values. May also be set to undef to pass through EXIF "ASCII" values without recoding. Set to "UTF8" to conform with the MWG recommendation.</td> <td align=center><i>(see <a href="#Charset">Charset</a> option)</i><br>or undef</td><td align=center>undef</td></tr> <tr id="CharsetFileName"><td>CharsetFileName</td><td>External character set used when specifying file names. When set in Windows, this triggers use of Windows Unicode file library routines (requires Win32API::File). May also be set to an empty string to avoid "encoding not specified" warnings on Windows.</td> <td align=center><i>(see <a href="#Charset">Charset</a> option)</i><br>or undef</td><td align=center>undef</td></tr> <tr id="CharsetID3"><td>CharsetID3</td><td>Internal encoding to assume for ID3v1 strings. By the specification ID3v1 strings should be encoded in ISO 8859-1 (essentially 'Latin'), but some applications may use local encoding instead. This option allows different encodings to be specified.</td> <td align=center><i>(see <a href="#Charset">Charset</a> option)</i></td><td align=center>'Latin'</td></tr> <tr id="CharsetIPTC"><td>CharsetIPTC</td><td>Fallback internal IPTC character set to assume if IPTC information contains no CodedCharacterSet tag.</td> <td align=center><i>(see <a href="#Charset">Charset</a> option)</i></td><td align=center>'Latin'</td></tr> <tr id="CharsetPhotoshop"><td>CharsetPhotoshop</td><td>Internal encoding to assume for Photoshop IRB resource names.</td> <td align=center><i>(see <a href="#Charset">Charset</a> option)</i></td><td align=center>'Latin'</td></tr> <tr id="CharsetQuickTime"><td>CharsetQuickTime</td><td>Internal encoding to assume for QuickTime strings stored with an unspecified encoding.</td> <td align=center><i>(see <a href="#Charset">Charset</a> option)</i></td><td align=center>'MacRoman'</td></tr> <tr id="CharsetRIFF"><td>CharsetRIFF</td><td>Internal encoding to assume for strings in RIFF metadata (eg. AVI and WAV files). The default value of 0 assumes 'Latin' encoding unless otherwise specified by the RIFF CSET chunk. Set to undef to pass through strings without recoding.</td> <td align=center><i>(see <a href="#Charset">Charset</a> option)</i><br>or 0 or undef</td><td align=center>0</td></tr> <tr id="Compact"><td>Compact</td><td>Flag to write compact output. The XMP specification suggests that the data be padded with blanks to allow in-place editing. With this flag set the 2kB of padding is not written. Note that this only effects embedded XMP since padding is never written for stand-alone XMP files.</td> <td align=center>0 or 1</td><td align=center>undef</td></tr> <tr id="Composite"><td>Composite</td><td>Flag to generate Composite tags when extracting information.</td> <td align=center>0 or 1</td><td align=center>1</td></tr> <tr id="Compress"><td>Compress</td><td>Flag to write new values in compressed format if possible. Has no effect unless Compress::Zlib is installed.</td> <td align=center>0 or 1</td><td align=center>undef</td></tr> <tr id="CoordFormat"><td>CoordFormat</td><td>Specify output format for GPS coordinates.</td> <td>A printf-style format string with specifiers for degrees, minutes and seconds in that order, however minutes and seconds may be omitted. If the hemisphere is known, a reference direction (N, S, E or W) is appended to each printed coordinate, but adding a '<code>+</code>' to the first format specifier (eg. <code>'%+.6f'</code>) prints a signed coordinate instead. The default for reading is equivalent to a format string of <code>q{%d deg %d' %.2f"}</code>, but to avoid a loss of precision the default for copying tags with <a href="#SetNewValuesFromFile">SetNewValuesFromFile</a> is <code>q{%d %d %.8f}</code>. </td><td align=center>undef</td></tr> <tr id="DateFormat"><td>DateFormat</td><td>Output format for date/time values. If date can not be converted, value is left unchanged unless the StrictDate option is set. Timezones are ignored. The inversion conversion (ie. when calling <a href="#SetNewValue">SetNewValue</a>) is performed only if POSIX::strptime or Time::Piece is installed.</td> <td>See strftime manpage for details. The default setting of undef causes date/time values to remain in standard EXIF format (similar to a DateFormat of <code>"%Y:%m:%d %H:%M:%S"</code>).</td> <td align=center>undef</td></tr> <tr id="Duplicates"><td>Duplicates</td><td>Flag to return values from tags with duplicate names when extracting information.</td> <td align=center>0 or 1</td><td align=center>1</td></tr> <tr id="Escape"><td>Escape</td> <td>Escape special characters in extracted values for HTML or XML. Also unescapes HTML or XML character entities in input values passed to <a href="#SetNewValue">SetNewValue</a>.</td> <td align=center>HTML, XML or undef</td> <td align=center>undef</td></tr> <tr id="Exclude"><td>Exclude</td> <td>Exclude specified tags when extracting information.</td> <td>Tag name or reference to a list of tag names to exclude. Case is not significant. Tags may also be excluded by preceding their name with a '-' in the arguments to ImageInfo.</td> <td align=center>undef</td></tr> <tr id="ExtendedXMP"><td>ExtendedXMP</td><td>This setting affects the reading and editing of extended XMP in JPEG images. According to the XMP specification, extended XMP is only valid if it has the GUID specified by the <a href="TagNames/XMP.html#xmpNote">HasExtendedXMP tag</a>. ExifTool 9.95 and earlier would read extended XMP regardless of GUID, but with the addition of this option in version 9.96 the default behaviour was changed to conform with the XMP specification (to read only extended XMP with the proper GUID). This option should be set to 2 to emulate pre-9.96 behaviour and read all extended XMP. It may also be set to a GUID to read a specific extended XMP, or 0 to ignore extended XMP entirely.</td> <td><table class=clear> <tr><td valign=top align=right><b>0</b> =</td><td>ignore extended XMP</td></tr> <tr><td valign=top align=right><b>1</b> =</td><td>valid GUID only</td></tr> <tr><td valign=top align=right><b>2</b> =</td><td>any GUID</td></tr> <tr><td valign=top align=right><i>guid</i> =</td><td>specific GUID</td></tr> </table></td><td align=center>1</td></tr> <tr id="ExtractEmbedded"><td>ExtractEmbedded</td> <td>Flag to extract information from embedded documents in EPS files, embedded EPS information and JPEG and Jpeg2000 images in PDF files, embedded MPF images in JPEG and MPO files, streaming metadata in AVCHD videos, and the resource fork of Mac OS files.</td> <td align=center>0 or 1</td><td align=center>undef</td></tr> <tr id="FastScan"><td>FastScan</td> <td>Flag to increase speed of extracting information from JPEG images. With this option set to 1, ExifTool will not scan to the end of a JPEG image to check for an AFCP, CanonVRD, FotoStation, PhotoMechanic, MIE or PreviewImage trailer. This also stops the parsing after the first comment in GIF images, and at the audio/video data with RIFF-format files (AVI, WAV, etc), so any trailing metadata (eg. XMP written by some utilities) may be missed. When combined with the ScanForXMP option, prevents scanning for XMP in recognized file types. With a value of 2, ExifTool will also avoid extracting any EXIF MakerNote information. When set to 3, the file is not actually parsed, and only an initial guess at FileType and some pseudo tags are returned. </td> <td align=center>0, 1, 2 or 3</td><td align=center>undef</td></tr> <tr id="Filter"><td>Filter</td> <td>Perl expression used to filter all returned tag values. Applies to PrintConv values only.</td><td>Expression to act on the value of the Perl default variable ($_), changing the value of this variable as required. The value is not changed if $_ is set to undef.</td> <td align=center>undef</td></tr> <tr id="FixBase"><td>FixBase</td> <td>Fix maker notes base offset. Allows values to be extracted from maker notes which have been corrupted by editing with 3rd party software.</td> <td>An integer specifying a value to be added to the maker notes base offset, or the empty string ('') for ExifTool to take its best guess at the correct base.</td> <td align=center>undef</td></tr> <tr id="GeoMaxIntSecs"><td>GeoMaxIntSecs</td> <td>Maximum interpolation time in seconds for geotagging. Geotagging is treated as an extrapolation if the Geotime value lies between two fixes in the same track which are separated by a number of seconds greater than this. Otherwise, the coordinates are calculated as a linear interpolation between the nearest fixes on either side of the Geotime value. Set to 0 to disable interpolation and use the coordinates of the nearest fix instead (provided it is within GeoMaxExtSecs, otherwise geotagging fails).</td> <td align=center>A floating point number</td> <td align=center>1800</td></tr> <tr id="GeoMaxExtSecs"><td>GeoMaxExtSecs</td> <td>Maximum extrapolation time in seconds for geotagging. Geotagging fails if the Geotime value lies outside a GPS track by a number of seconds greater than this. Otherwise, the coordinates of the nearest fix are taken.</td> <td align=center>A floating point number</td> <td align=center>1800</td></tr> <tr id="GeoMaxHDOP"><td>GeoMaxHDOP</td> <td>Maximum Horizontal (2D) Dilution Of Precision for geotagging. GPS fixes are ignored if the HDOP is greater than this.</td> <td align=center>A floating point number, or undef</td> <td align=center>undef</td></tr> <tr id="GeoMaxPDOP"><td>GeoMaxPDOP</td> <td>Maximum Position (3D) Dilution Of Precision for geotagging. GPS fixes are ignored if the PDOP is greater than this.</td> <td align=center>A floating point number, or undef</td> <td align=center>undef</td></tr> <tr id="GeoMinSats"><td>GeoMinSats</td> <td>Minimum number of satellites for geotagging. GPS fixes are ignored if the number of acquired satellites is less than this.</td> <td align=center>A positive integer, or undef</td> <td align=center>undef</td></tr> <tr id="GlobalTimeShift"><td>GlobalTimeShift</td> <td>Time shift to apply to all extracted date/time PrintConv values. Does not affect ValueConv values.</td> <td align=center>Date/time shift string with leading '-' for negative shifts<br>(see <a href="Shift.html">Image::ExifTool::Shift.pl</a>)</td> <td align=center>undef</td></tr> <tr id="GroupNum"><td>Group#</td><td>Extract tags only for specified groups in family # (Group0 assumed if # not given).</td> <td>Group name or reference to list of group names. Group name may begin with '-' to exclude a group. Case IS significant. See <a href="#GetGroup">GetGroup</a> for a description of group families, and <a href="#GetAllGroups">GetAllGroups</a> for a list of available groups.</td> <td align=center>undef</td></tr> <tr id="HtmlDump"><td>HtmlDump</td><td>Dump information in hex to a dynamic HTML web page. Option value sets a limit on the maximum block size. Output file is specified by the TextOut option.</td> <td><table class=clear> <tr><td valign=top align=center><b>0</b> =</td><td>No HTML dump</td></tr> <tr><td valign=top align=center><b>1</b> =</td><td>1 KB size limit</td></tr> <tr><td valign=top align=center><b>2</b> =</td><td>16 KB size limit</td></tr> <tr><td valign=top align=center><b>3</b> =</td><td>Full dump</td></tr> </table></td><td align=center>0</td></tr> <tr id="HtmlDumpBase"><td>HtmlDumpBase</td><td>Base for HTML dump offsets. If not defined, the EXIF/TIFF base offset is used.</td> <td><table class=clear> <tr><td valign=top align=right><b>0</b> =</td><td>Absolute offsets</td></tr> <tr><td valign=top align=right><i>non‑zero</i> =</td><td>Relative offsets</td></tr> <tr><td valign=top align=right><b>undef</b> =</td><td>EXIF/TIFF offsets</td></tr> </table></td><td align=center>undef</td></tr> <tr id="IgnoreMinorErrors"><td>IgnoreMinorErrors</td><td>Flag to ignore minor errors. Causes minor errors to be downgraded to warnings, and minor warnings to be ignored. This option is provided mainly to allow writing of files when minor errors occur, but by ignoring some minor warnings the behaviour of ExifTool may be changed to allow some questionable operations to proceed (such as extracting thumbnail and preview images even if they don't have a recognizable header). Minor errors/warnings are denoted by "[minor]" at the start of the message, or "[Minor]" (with a capital "M") for warnings that affect processing when ignored.</td> <td align=center>0 or 1</td><td align=center>undef</td></tr> <tr id="Lang"><td>Lang</td><td>Localized language for exiftool tag descriptions, etc. If the specified language isn't available, the option is not changed. May be set to undef to select the built-in default language.</td> <td align=left>Image::ExifTool::Lang module name (eg. 'fr', 'zh_cn'), or 'en' or undef for the default language.</td> <td align=center>'en'</td></tr> <tr id="LargeFileSupport"><td>LargeFileSupport</td><td>Flag to indicate that 64-bit file offsets are supported on this system.</td> <td align=center>0 or 1</td><td align=center>undef</td></tr> <tr id="List"><td>List</td><td>Flag to extract lists of PrintConv values into arrays instead of combining them into a string of values.</td><td align=center>0 or 1</td><td align=center>undef</td></tr> <tr id="ListItem"><td>ListItem</td><td>Return only a specific item from list-type values. A value of 0 returns the first item in each list, 1 returns the second item, etc. Negative indices may also be used, with -1 representing the last item in the list. Applies only to the top-level list of nested lists.</td> <td align=center>An integer, or undef</td><td align=center>undef</td></tr> <tr id="ListSep"><td>ListSep</td><td>Separator string used to join lists of PrintConv values when List option is not set.</td><td align=center>Any string</td><td align=center>', '</td></tr> <tr id="ListSplit"><td>ListSplit</td><td>Regular expression used to split values of list-type tags into individual items when writing. (eg. use ',\\s*' to split a comma-separated list)</td> <td align=center>A regular expression pattern</td><td align=center>undef</td></tr> <tr id="MakerNotes"><td>MakerNotes</td><td>Option to extract MakerNotes and other writable subdirectories (such as PrintIM) as a data block. Normally when the MakerNotes are extracted they are rebuilt to include data outside the boundaries of the original maker note data block, but a value of 2 disables this feature.</td> <td><table class=clear> <tr><td valign=top align=center><b>0</b> =</td><td>Don't extract writable subdirectories</td></tr> <tr><td valign=top align=center><b>1</b> =</td><td>Extract and rebuild makernotes into self-contained block</td></tr> <tr><td valign=top align=center><b>2</b> =</td><td>Extract without rebuilding makernotes</td></tr> </table></td><td align=center>undef</td></tr> <tr id="MDItemTags"><td>MDItemTags</td><td>Flag to extract the OS X metadata item tags (see the "mdls" man page and the <a href="TagNames/MacOS.html#MDItem">MacOS MDItem Tags documentation</a> for more information).</td> <td align=center>0 or 1</td><td align=center>undef</td></tr> <tr id="MissingTagValue"><td>MissingTagValue</td><td>Value for missing tags in expressions evaluated by <a href="#SetNewValuesFromFile">SetNewValuesFromFile</a>. If not set, a minor error is issued for missing values, or the value is set to '' if IgnoreMinorErrors is set.</td> <td align=center>Any string, or undef</td><td align=center>undef</td></tr> <tr id="NoPDFList"><td>NoPDFList</td><td>Flag to avoid splitting PDF list-type tag values into separate items.</td> <td align=center>0 or 1</td><td align=center>undef</td></tr> <tr id="Password"><td>Password</td><td>Password for reading/writing password-protected PDF documents. Ignored if a password is not required. Character encoding of the password is determined by the value of the Charset option at processing time.</td> <td align=center>Any string</td><td align=center>undef</td></tr> <tr id="PNGEarlyXMP"><td>PNGEarlyXMP</td><td>Flag to write XMP in PNG images before the IDAT (image data) chunk. By default, ExifTool adds new XMP to the end of a PNG file (just before IEND). This is allowed by the PNG and XMP specifications, but some utilities seem to ignore XMP if it comes after the image data. The PNGEarlyXMP option causes ExifTool to instead add new XMP before the PNG IDAT chunk. However, since ExifTool uses a single-pass writing algorithm, it has no way to tell if XMP already exists later in the file before writing the new XMP in this location. If this happens, a minor error is issued when the extra XMP is encountered, and the file is not written. Adding the <a href="#IgnoreMinorErrors">IgnoreMinorErrors</a> option causes the XMP after IDAT to be deleted, thus resolving the conflict (at the expense of possible metadata loss), and allowing the file to be written. The PNGEarlyXMP option is applied automatically when deleting all XMP and writing new XMP back in one step. When reading, this option causes a warning to be issued if standard XMP is found after the IDAT chunk.</td> <td align=center>0 or 1</td><td align=center>undef</td></tr> <tr id="PrintConv"><td>PrintConv</td><td>Flag to enable print conversion. Also enables inverse print conversion for writing.</td><td align=center>0 or 1</td><td align=center>1</td></tr> <tr id="QuickTimeUTC"><td>QuickTimeUTC</td><td>Flag set to assume that QuickTime date/time values are stored as UTC, causing conversion to local time when they are extracted. According to the QuickTime specification date/time values should be UTC, but many digital cameras store local time instead (presumably because they don't know the time zone). This option also disables the autodetection of incorrect time-zero offsets in QuickTime date/time values, and enforces a time zero of 1904 as per the QuickTime specification.</td><td align=center>0 or 1</td><td align=center>undef</td></tr> <tr id="RequestAll"><td>RequestAll</td><td>Flag to request all tags to be extracted. This causes some tags to be generated which normally would not be unless specifically requested (by passing the tag name to <a href="#ImageInfo">ImageInfo</a> or <a href="#ExtractInfo">ExtractInfo</a>). May be set to 2 or 3 to enable generation of some additional tags mentioned in the tag name documentation.</td> <td align=center>0, 1, 2 or 3</td><td align=center>undef</td></tr> <tr id="RequestTags"><td>RequestTags</td><td>List of additional tag and/or group names to request in the next call to <a href="#ExtractInfo">ExtractInfo</a>. This option is useful only for tags/groups which aren't extracted unless specifically requested. Groups are requested by adding a colon after the name (eg. "MacOS:"). Names are converted to lower case as they are added to the list.</td><td>List reference, delimited string of names (any delimiter is allowed), or undef to clear the previous RequestTags list.</td> <td align=center>undef</td></tr> <tr id="ScanForXMP"><td>ScanForXMP</td><td>Flag to scan all files (even unrecognized formats) for XMP information unless XMP was already found in the file. When combined with the FastScan option, only unrecognized file types are scanned for XMP. </td><td align=center>0 or 1</td><td align=center>undef</td></tr> <tr id="Sort"><td>Sort</td><td>Specifies order to sort tags in the returned tag list.</td> <td><table class=clear> <tr><td valign=top align=right><b>Input</b> =</td><td>Sort in same order as input tag arguments</td></tr> <tr><td valign=top align=right><b>File</b> =</td><td>Sort in order that tags were found in the file</td></tr> <tr><td valign=top align=right><b>Tag</b> =</td><td>Sort alphabetically by tag name</td></tr> <tr><td valign=top align=right><b>Descr</b> =</td><td>Sort by tag description (with current Lang setting)</td></tr> <tr valign=top><td valign=top align=right><b>Group#</b> =</td><td>Sort by tag group, where # is zero or more family numbers separated by colons. If # is not specified, Group0 is assumed. See <a href="#GetGroup">GetGroup</a> for a description of group families.</td></tr> </table></td><td align=center>'Input'</td></tr> <tr id="Sort2"><td>Sort2</td><td>Secondary sort order used for tags within each group when Sort is 'Group'.</td> <td><table class=clear> <tr><td valign=top align=right><b>File</b> =</td><td>Sort in order that tags were found in the file</td></tr> <tr><td valign=top align=right><b>Tag</b> =</td><td>Sort alphabetically by tag name</td></tr> <tr><td valign=top align=right><b>Descr</b> =</td><td>Sort by tag description (with current Lang setting)</td></tr> </table></td><td align=center>'File'</td></tr> <tr id="StrictDate"><td>StrictDate</td><td>Flag to return undefined value for any date which can't be converted when the DateFormat option is used.</td> <td><table class=clear> <tr><td valign=top align=right><b>undef</b> =</td><td>Same as 0 for reading and 1 for copying</td></tr> <tr><td valign=top align=right><b>0</b> =</td><td>Return bad date/time values unchanged</td></tr> <tr><td valign=top align=right><b>1</b> =</td><td>Return undef if date/time value can't be converted</td></tr> </table></td><td align=center>undef</td></tr> <tr id="Struct"><td>Struct</td><td>Flag to return XMP structures as HASH references instead of flattening into individual tags. This setting has no effect when writing since both flattened or structured tags may always be written. See the <a href="struct.html">Structured Information documentation</a> for more details about structured information.</td> <td><table class=clear> <tr><td valign=top align=right><b>undef</b> =</td><td>Same as 0 for reading and 2 for copying</td></tr> <tr><td valign=top align=right><b>0</b> =</td><td>Read/copy flattened tags</td></tr> <tr><td valign=top align=right><b>1</b> =</td><td>Read/copy structures</td></tr> <tr><td valign=top align=right><b>2</b> =</td><td>Read/copy both flattened and structured tags, but flag flattened tags as "unsafe" for copying</td></tr> </table></td><td align=center>undef</td></tr> <tr id="SystemTags"><td>SystemTags</td><td>Flag to extract the following additional File System tags: FileAttributes, FileDeviceNumber, FileInodeNumber, FileHardLinks, FileUserID, FileGroupID, FileDeviceID, FileBlockSize and FileBlockCount.</td> <td align=center>0 or 1</td><td align=center>undef</td></tr> <tr id="TextOut"><td>TextOut</td><td>Output file for Verbose and HtmlDump options.</td> <td align=center>File reference</td><td align=center>\*STDOUT</td></tr> <tr id="Unknown"><td>Unknown</td><td>Control extraction of unknown tags.</td> <td><table class=clear> <tr><td valign=top align=center><b>0</b> =</td><td>Unknown tags not extracted</td></tr> <tr><td valign=top align=center><b>1</b> =</td><td>Unknown tags are extracted from EXIF (and other tagged-format) directories</td></tr> <tr><td valign=top align=center><b>2</b> =</td><td>Unknown tags also extracted from binary data blocks</td></tr> </table></td><td align=center>0</td></tr> <tr id="UserParam"><td>UserParam</td><td>Special option to set/get user-defined parameters. Useful to allow external input into tag name expressions and ValueConv logic. <i>PARAM</i> is the user-defined parameter name (case insensitive). These parameters may be accessed in tag name expressions by prefixing the parameter name with a dollar sign, just like normal tags. If called without no additional arguments, <code>Options('UserParam')</code> returns a reference to the hash of all user parameters (with lower-case names). </td> <td><table class=clear> <tr><td valign=top><i>PARAM</i></td><td valign=top>-</td><td>Get parameter</td></tr> <tr><td valign=top><i>PARAM=</i></td><td valign=top>-</td><td>Clear parameter</td></tr></table> <table class=clear> <tr><td valign=top><i>PARAM=VALUE</i></td><td valign=top>-</td><td>Set parameter</td></tr> </table><table class=clear> <tr><td valign=top><i>hash ref</i></td><td valign=top>-</td><td>Set UserParam hash</td></tr> <tr><td valign=top><b>undef</b></td><td valign=top>-</td><td>Clear UserParam hash</td></tr> </table> </td><td align=center>{ }</td></tr> <tr id="Validate"><td>Validate</td><td>[Experimental] Flag to perform extra validation checks when reading, causing extra warnings to be generated if problems are found.</td> <td align=center>0 or 1</td><td align=center>undef</td></tr> <tr id="Verbose"><td>Verbose</td><td>Print verbose messages to file specified by TextOut option. <a href="verbose.html">Click here</a> for example outputs.</td> <td><table class=clear> <tr><td valign=top align=center><b>0</b> =</td><td>No verbose messages</td></tr> <tr><td valign=top align=center><b>1</b> =</td><td>Print tag names and raw values</td></tr> <tr><td valign=top align=center><b>2</b> =</td><td>Add additional tag details</td></tr> <tr><td valign=top align=center><b>3</b> =</td><td>Add hex dump of tag data (with length limits)</td></tr> <tr><td valign=top align=center><b>4</b> =</td><td>Remove length limit on dump of tag values</td></tr> <tr><td valign=top align=center><b>5</b> =</td><td>Remove length limit on dump of JPEG segments</td></tr> </table></td><td align=center>0</td></tr> <tr id="WriteMode"><td>WriteMode</td><td>Set tag write/create mode.</td> <td>A string with one or more of these characters:<table class=clear> <tr><td valign=top align=center><b>w</b> =</td><td><b>W</b>rite existing tags</td></tr> <tr><td valign=top align=center><b>c</b> =</td><td><b>C</b>reate new tags</td></tr> <tr><td valign=top align=center><b>g</b> =</td><td>Create new <b>g</b>roups <sup>&dagger;</sup></td></tr> </table></td><td align=center>'wcg'</td></tr> <tr id="XAttrTags"><td>XAttrTags</td><td>Flag to extract the OS X extended attribute tags (see the "xattr" man page and the <a href="TagNames/MacOS.html#XAttr">MacOS XAttr Tags documentation</a> for more information).</td> <td align=center>0 or 1</td><td align=center>undef</td></tr> <tr id="XMPAutoConv"><td>XMPAutoConv</td><td>Flag to enable automatic conversion for unknown XMP tags with values that look like rational numbers or dates.</td> <td align=center>0 or 1</td> <td align=center>1</td></tr> </table></blockquote> <blockquote><table><tr><td valign=top><sup>&dagger;</sup></td><td>The level of the group differs for different types of metadata. For XMP or IPTC this is the full XMP/IPTC block (the family 0 group), but for EXIF this is the individual IFD (the family 1 group).</td></tr></table></blockquote> <p><b>Examples:</b></p> <blockquote><table class='box'><tr><td><pre> <span class=com># exclude the 'OwnerName' tag from returned information</span> $exifTool-><b>Options</b>(Exclude => 'OwnerName'); </pre></td></tr></table></blockquote> <blockquote