1Image::ExifTool(3)    User Contributed Perl Documentation   Image::ExifTool(3)
2
3
4

NAME

6       Image::ExifTool - Read and write meta information
7

SYNOPSIS

9         use Image::ExifTool qw(:Public);
10
11         # ---- Simple procedural usage ----
12
13         # Get hash of meta information tag names/values from an image
14         $info = ImageInfo('a.jpg');
15
16         # ---- Object-oriented usage ----
17
18         # Create a new Image::ExifTool object
19         $exifTool = Image::ExifTool->new;
20
21         # Extract meta information from an image
22         $exifTool->ExtractInfo($file, \%options);
23
24         # Get list of tags in the order they were found in the file
25         @tagList = $exifTool->GetFoundTags('File');
26
27         # Get the value of a specified tag
28         $value = $exifTool->GetValue($tag, $type);
29
30         # Get a tag description
31         $description = $exifTool->GetDescription($tag);
32
33         # Get the group name associated with this tag
34         $group = $exifTool->GetGroup($tag, $family);
35
36         # Set a new value for a tag
37         $exifTool->SetNewValue($tag, $newValue);
38
39         # Write new meta information to a file
40         $success = $exifTool->WriteInfo($srcfile, $dstfile);
41
42         # ...plus a host of other useful methods...
43

DESCRIPTION

45       Reads and writes meta information in a wide variety of files, including
46       the maker notes of many digital cameras by various manufacturers such
47       as Canon, Casio, DJI, FLIR, FujiFilm, GE, GoPro, HP, JVC/Victor, Kodak,
48       Leaf, Minolta/Konica-Minolta, Nikon, Nintendo, Olympus/Epson,
49       Panasonic/Leica, Pentax/Asahi, Phase One, Reconyx, Ricoh, Samsung,
50       Sanyo, Sigma/Foveon and Sony.
51
52       Below is a list of file types and meta information formats currently
53       supported by ExifTool (r = read, w = write, c = create):
54
55         File Types
56         ------------+-------------+-------------+-------------+------------
57         360   r/w   | DPX   r     | ITC   r     | NUMBERS r   | RAW   r/w
58         3FR   r     | DR4   r/w/c | J2C   r     | O     r     | RIFF  r
59         3G2   r/w   | DSS   r     | JNG   r/w   | ODP   r     | RSRC  r
60         3GP   r/w   | DV    r     | JP2   r/w   | ODS   r     | RTF   r
61         7Z    r     | DVB   r/w   | JPEG  r/w   | ODT   r     | RW2   r/w
62         A     r     | DVR-MS r    | JSON  r     | OFR   r     | RWL   r/w
63         AA    r     | DYLIB r     | JXL   r     | OGG   r     | RWZ   r
64         AAE   r     | EIP   r     | K25   r     | OGV   r     | RM    r
65         AAX   r/w   | EPS   r/w   | KDC   r     | ONP   r     | SEQ   r
66         ACR   r     | EPUB  r     | KEY   r     | OPUS  r     | SKETCH r
67         AFM   r     | ERF   r/w   | LA    r     | ORF   r/w   | SO    r
68         AI    r/w   | EXE   r     | LFP   r     | ORI   r/w   | SR2   r/w
69         AIFF  r     | EXIF  r/w/c | LIF   r     | OTF   r     | SRF   r
70         APE   r     | EXR   r     | LNK   r     | PAC   r     | SRW   r/w
71         ARQ   r/w   | EXV   r/w/c | LRV   r/w   | PAGES r     | SVG   r
72         ARW   r/w   | F4A/V r/w   | M2TS  r     | PBM   r/w   | SWF   r
73         ASF   r     | FFF   r/w   | M4A/V r/w   | PCD   r     | THM   r/w
74         AVI   r     | FITS  r     | MACOS r     | PCX   r     | TIFF  r/w
75         AVIF  r/w   | FLA   r     | MAX   r     | PDB   r     | TORRENT r
76         AZW   r     | FLAC  r     | MEF   r/w   | PDF   r/w   | TTC   r
77         BMP   r     | FLIF  r/w   | MIE   r/w/c | PEF   r/w   | TTF   r
78         BPG   r     | FLV   r     | MIFF  r     | PFA   r     | TXT   r
79         BTF   r     | FPF   r     | MKA   r     | PFB   r     | VCF   r
80         CHM   r     | FPX   r     | MKS   r     | PFM   r     | VNT   r
81         COS   r     | GIF   r/w   | MKV   r     | PGF   r     | VRD   r/w/c
82         CR2   r/w   | GLV   r/w   | MNG   r/w   | PGM   r/w   | VSD   r
83         CR3   r/w   | GPR   r/w   | MOBI  r     | PLIST r     | WAV   r
84         CRM   r/w   | GZ    r     | MODD  r     | PICT  r     | WDP   r/w
85         CRW   r/w   | HDP   r/w   | MOI   r     | PMP   r     | WEBP  r/w
86         CS1   r/w   | HDR   r     | MOS   r/w   | PNG   r/w   | WEBM  r
87         CSV   r     | HEIC  r/w   | MOV   r/w   | PPM   r/w   | WMA   r
88         CUR   r     | HEIF  r/w   | MP3   r     | PPT   r     | WMV   r
89         CZI   r     | HTML  r     | MP4   r/w   | PPTX  r     | WPG   r
90         DCM   r     | ICC   r/w/c | MPC   r     | PS    r/w   | WTV   r
91         DCP   r/w   | ICO   r     | MPG   r     | PSB   r/w   | WV    r
92         DCR   r     | ICS   r     | MPO   r/w   | PSD   r/w   | X3F   r/w
93         DFONT r     | IDML  r     | MQV   r/w   | PSP   r     | XCF   r
94         DIVX  r     | IIQ   r/w   | MRC   r     | QTIF  r/w   | XISF  r
95         DJVU  r     | IND   r/w   | MRW   r/w   | R3D   r     | XLS   r
96         DLL   r     | INSP  r/w   | MXF   r     | RA    r     | XLSX  r
97         DNG   r/w   | INSV  r     | NEF   r/w   | RAF   r/w   | XMP   r/w/c
98         DOC   r     | INX   r     | NKSC  r/w   | RAM   r     | ZIP   r
99         DOCX  r     | ISO   r     | NRW   r/w   | RAR   r     |
100
101         Meta Information
102         ----------------------+----------------------+---------------------
103         EXIF           r/w/c  |  CIFF           r/w  |  Ricoh RMETA    r
104         GPS            r/w/c  |  AFCP           r/w  |  Picture Info   r
105         IPTC           r/w/c  |  Kodak Meta     r/w  |  Adobe APP14    r
106         XMP            r/w/c  |  FotoStation    r/w  |  MPF            r
107         MakerNotes     r/w/c  |  PhotoMechanic  r/w  |  Stim           r
108         Photoshop IRB  r/w/c  |  JPEG 2000      r    |  DPX            r
109         ICC Profile    r/w/c  |  DICOM          r    |  APE            r
110         MIE            r/w/c  |  Flash          r    |  Vorbis         r
111         JFIF           r/w/c  |  FlashPix       r    |  SPIFF          r
112         Ducky APP12    r/w/c  |  QuickTime      r    |  DjVu           r
113         PDF            r/w/c  |  Matroska       r    |  M2TS           r
114         PNG            r/w/c  |  MXF            r    |  PE/COFF        r
115         Canon VRD      r/w/c  |  PrintIM        r    |  AVCHD          r
116         Nikon Capture  r/w/c  |  FLAC           r    |  ZIP            r
117         GeoTIFF        r/w/c  |  ID3            r    |  (and more)
118

CONFIGURATION

120       User-defined tags can be added via the ExifTool configuration file, or
121       by defining the %Image::ExifTool::UserDefined hash before calling any
122       ExifTool methods.  See "ExifTool_config" in the ExifTool distribution
123       for more details.
124
125       By default ExifTool looks for a configuration file named
126       ".ExifTool_config" first in your home directory, then in the directory
127       of the application script, but a different directory may be specified
128       by setting the EXIFTOOL_HOME environment variable, or a different file
129       may be specified by setting the ExifTool "configFile" variable before
130       using Image::ExifTool.  For example:
131
132           BEGIN { $Image::ExifTool::configFile = '/Users/phil/myconfig.cfg' }
133           use Image::ExifTool;
134
135       The configuration feature may also be disabled by setting "configFile"
136       to an empty string:
137
138           BEGIN { $Image::ExifTool::configFile = '' }
139           use Image::ExifTool;
140

EXPORTS

142       Exports nothing by default, but "ImageInfo" and all static methods may
143       be exported with the ":Public" export list.
144

METHODS

146       All ExifTool features are accessed through the methods of the public
147       interface listed below.  Other Image::ExifTool methods and modules
148       should not be accessed directly because their interface may change with
149       future versions.
150
151       None of these methods should ever die or issue warnings to STDERR if
152       called with the proper arguments (with the exception of "SetNewValue"
153       which may send an error message to STDERR, but only when called in
154       scalar context).  Error and warning messages that occur during
155       processing are stored in the values of the Error and Warning tags, and
156       are accessible via the "GetValue" method to retrieve a single Error or
157       Warning message, or "GetInfo" to retrieve any number of them.
158
159       The ExifTool methods are not thread safe.
160
161   new
162       Creates a new ExifTool object.
163
164           $exifTool = Image::ExifTool->new;
165
166       One ExifTool object may be used to process many files, so creating
167       multiple ExifTool objects usually is not necessary.
168
169       Note that ExifTool uses AUTOLOAD to load non-member methods, so any
170       class using Image::ExifTool as a base class must define an AUTOLOAD
171       which calls Image::ExifTool::DoAutoLoad().  eg)
172
173           sub AUTOLOAD
174           {
175               Image::ExifTool::DoAutoLoad($AUTOLOAD, @_);
176           }
177
178   ImageInfo
179       Read image file and return meta information.  This is the one step
180       function for retrieving meta information from an image.  Internally,
181       "ImageInfo" calls "ExtractInfo" to extract the information, "GetInfo"
182       to generate the information hash, and "GetTagList" for the returned tag
183       list.
184
185           # return meta information for 2 tags only (procedural)
186           $info = ImageInfo($filename, $tag1, $tag2);
187
188           # return information about an open image file (object-oriented)
189           $info = $exifTool->ImageInfo(\*FILE);
190
191           # return information from image data in memory for specified tags
192           %options = (PrintConv => 0);
193           @tagList = qw(filename imagesize xmp:creator exif:* -ifd1:*);
194           $info = ImageInfo(\$imageData, \@tagList, \%options);
195
196           # extract information from an embedded thumbnail image
197           $info = ImageInfo('image.jpg', 'thumbnailimage');
198           $thumbInfo = ImageInfo($$info{ThumbnailImage});
199
200       Inputs:
201           "ImageInfo" is very flexible about the input arguments, and
202           interprets them based on their type.  It may be called with one or
203           more arguments.  The one required argument is either a SCALAR (the
204           image file name), a file reference (a reference to the image file)
205           or a SCALAR reference (a reference to the image in memory).  Other
206           arguments are optional.  The order of the arguments is not
207           significant, except that the first SCALAR is taken to be the file
208           name unless a file reference or scalar reference comes earlier in
209           the argument list.
210
211           Below is an explanation of how the "ImageInfo" function arguments
212           are interpreted:
213
214           ExifTool ref
215               "ImageInfo" may be called with an ExifTool object if desired.
216               Advantages of using the object-oriented form are that options
217               may be set before calling "ImageInfo", and the object may be
218               used afterward to access member functions.  Must be the first
219               argument if used.
220
221           SCALAR
222               The first scalar argument is taken to be the file name unless
223               an earlier argument specified the image data via a file
224               reference (file ref) or data reference (SCALAR ref).  The
225               remaining scalar arguments are names of tags for requested
226               information.  All tags are returned if no tags are specified.
227
228               Tag names are case-insensitive and may be prefixed by optional
229               group names separated by colons.  A group name may begin with a
230               family number (eg.  '1IPTC:Keywords'), to restrict matches to a
231               specific family.  In the tag name, a '?' matches any single
232               character and a '*' matches zero or more characters.  Thus
233               'GROUP:*' represents all tags in a specific group.  Wildcards
234               may not be used in group names, with the exception that a group
235               name of '*' may be used to extract all available instances of a
236               tag regardless of the "Duplicates" setting (eg.
237               '*:WhiteBalance').  Multiple groups may be specified (eg.
238               'EXIF:Time:*' extracts all EXIF Time tags). And finally, a
239               leading '-' indicates a tag to be excluded (eg. '-IFD1:*'), or
240               a trailing '#' causes the ValueConv value to be returned for
241               this tag.
242
243               Note that keys in the returned information hash and elements of
244               the returned tag list are not necessarily the same as these tag
245               names because group names are removed, the case may be changed,
246               and an instance number may be added.  For this reason it is
247               best to use either the keys of the returned hash or the
248               elements of the returned tag list when accessing the tag
249               values.
250
251               See Image::ExifTool::TagNames for a complete list of ExifTool
252               tag names.
253
254           File ref
255               A reference to an open image file.  If you use this method (or
256               a SCALAR reference) to access information in an image, the
257               FileName and Directory tags will not be returned.  (Also, a
258               number of the File System tags will not be returned unless it
259               is a plain file.)  Image processing begins at the current file
260               position, and on return the file position is unspecified.  May
261               be either a standard filehandle, or a reference to a
262               File::RandomAccess object.  Note that the file remains open and
263               must be closed by the caller after "ImageInfo" returns.
264
265               [Advanced:  To allow a non-rewindable stream (eg. a network
266               socket) to be re-read after processing with ExifTool, first
267               wrap the file reference in a File::RandomAccess object, then
268               pass this object to "ImageInfo".  The File::RandomAccess object
269               will buffer the file if necessary, and may be used to re-read
270               the file after "ImageInfo" returns.]
271
272           SCALAR ref
273               A reference to image data in memory.
274
275           ARRAY ref
276               Reference to a list of tag names.  On entry, any elements in
277               the list are added to the list of requested tags.  Tags with
278               names beginning with '-' are excluded.  On return, this list is
279               updated to contain an ordered list of tag keys for the returned
280               information.
281
282               There will be 1:1 correspondence between the requested tags and
283               the returned tag keys only if the "Duplicates" option is 0 and
284               "Sort" is 'Input'.  (With "Duplicates" enabled, there may be
285               more entries in the returned list of tag keys, and with other
286               "Sort" settings the entries may not be in the same order as
287               requested.)  If a requested tag doesn't exist, a tag key is
288               still generated, but the tag value is undefined.
289
290               Note: Do not reuse this list in subsequent calls to "ImageInfo"
291               because it returns tag keys, not names, and the list will grow
292               for each call resulting in increasingly slower performance.
293
294           HASH ref
295               Reference to a hash containing the options settings valid for
296               this call only.  See "Options" documentation below for a list
297               of available options.  Options specified as arguments to
298               "ImageInfo" take precedence over "Options" settings.
299
300       Return Values:
301           "ImageInfo" returns a reference to a hash of tag-key/value pairs.
302           The tag keys are identifiers -- essentially case-sensitive tag
303           names with an appended instance number if multiple tags with the
304           same name were extracted from the image.  Many of the ExifTool
305           functions require a tag key as an argument.  Use "GetTagName
306           [static]" to get the tag name for a given tag key.  Note that the
307           case of the tag names may not be the same as requested.  Here is a
308           simple example to print out the information returned by
309           "ImageInfo":
310
311               foreach (sort keys %$info) {
312                   print "$_ => $$info{$_}\n";
313               }
314
315           Values of the returned hash are usually simple scalars, but a
316           scalar reference is used to indicate binary data and an array
317           reference may be used to indicate a list.  Also, a hash reference
318           may be returned if the "Struct" option is used.  Lists of values
319           are joined by commas into a single string only if the PrintConv
320           option is enabled and the ListJoin option is enabled (which are the
321           defaults).  Note that binary values are not necessarily extracted
322           unless specifically requested, or the Binary option is enabled and
323           the tag is not specifically excluded.  If not extracted the value
324           is a reference to a string of the form "Binary data ##### bytes".
325
326           The code below gives an example of how to handle these return
327           values, as well as illustrating the use of other ExifTool
328           functions:
329
330               use Image::ExifTool;
331               my $exifTool = Image::ExifTool->new;
332               $exifTool->Options(Unknown => 1);
333               my $info = $exifTool->ImageInfo('a.jpg');
334               my $group = '';
335               my $tag;
336               foreach $tag ($exifTool->GetFoundTags('Group0')) {
337                   if ($group ne $exifTool->GetGroup($tag)) {
338                       $group = $exifTool->GetGroup($tag);
339                       print "---- $group ----\n";
340                   }
341                   my $val = $info->{$tag};
342                   if (ref $val eq 'SCALAR') {
343                       if ($$val =~ /^Binary data/) {
344                           $val = "($$val)";
345                       } else {
346                           my $len = length($$val);
347                           $val = "(Binary data $len bytes)";
348                       }
349                   }
350                   printf("%-32s : %s\n", $exifTool->GetDescription($tag), $val);
351               }
352
353       Notes:
354           ExifTool returns all values as byte strings of encoded characters.
355           Perl wide characters are not used.  See "CHARACTER ENCODINGS" for
356           details about the encodings.  By default, most returned values are
357           encoded in UTF-8.  For these, Encode::decode_utf8() may be used to
358           convert to a sequence of logical Perl characters.
359
360           As well as tags representing information extracted from the image,
361           the following Extra tags generated by ExifTool may be returned:
362
363               ExifToolVersion - The ExifTool version number.
364
365               Error - An error message if the image could not be processed.
366
367               Warning - A warning message if problems were encountered while
368                         processing the image.
369
370   Options
371       Get/set ExifTool options.  This function can be called to set the
372       default options for an ExifTool object.  Options set this way are in
373       effect for all function calls but may be overridden by options passed
374       as arguments to some functions.  Option names are not case sensitive,
375       but option values are.
376
377       The default option values may be changed by defining a
378       %Image::ExifTool::UserDefined::Options hash.  See the ExifTool_config
379       file in the full ExifTool distribution for examples.  Unless otherwise
380       noted, a default of undef has the same effect as a value of 0 for
381       options with numerical values.
382
383           # exclude the 'OwnerName' tag from returned information
384           $exifTool->Options(Exclude => 'OwnerName');
385
386           # only get information in EXIF or MakerNotes groups
387           $exifTool->Options(Group0 => ['EXIF', 'MakerNotes']);
388
389           # ignore information from IFD1
390           $exifTool->Options(Group1 => '-IFD1');
391
392           # sort by groups in family 2, and extract unknown tags
393           $exifTool->Options(Sort => 'Group2', Unknown => 1);
394
395           # reset DateFormat option
396           $exifTool->Options(DateFormat => undef);
397
398           # do not extract duplicate tag names
399           $oldSetting = $exifTool->Options(Duplicates => 0);
400
401           # get current Verbose setting
402           $isVerbose = $exifTool->Options('Verbose');
403
404           # set a user parameter
405           $exifTool->Options(UserParam => 'MyParam=some value');
406
407       Inputs:
408           0) ExifTool object reference
409
410           1) Option parameter name (case-insensitive)
411
412           2) [optional] Option parameter value (may be undef to clear option)
413
414           3-N) [optional] Additional parameter/value pairs
415
416       Option Parameters:
417           Note that these API options may also be used in the exiftool
418           application via the command-line -api option.
419
420           Binary
421               Flag to extract the value data for all binary tags.  Tag values
422               representing large binary data blocks (eg. ThumbnailImage) are
423               not necessarily extracted unless this option is set or the tag
424               is specifically requested by name.  Default is undef.
425
426           BlockExtract
427               Flag to extract some directories (mentioned in the ExifTool tag
428               name documentation) as a block.  Setting this to a value of 2
429               also prevents parsing the block to extract tags contained
430               within.
431
432           ByteOrder
433               The byte order for newly created EXIF segments when writing.
434               Note that if EXIF information already exists, the existing
435               order is maintained.  Valid values are 'MM', 'II' and undef.
436               If ByteOrder is not defined (the default), then the maker note
437               byte order is used (if they are being copied), otherwise big-
438               endian ('MM') order is assumed.  This can also be set via the
439               ExifByteOrder tag, but the ByteOrder option takes precedence if
440               both are set.
441
442           ByteUnit
443               Units for print conversion of FileSize and other byte values.
444               Either 'SI' (eg. kB for 1000 bytes) or 'Binary' (eg. KiB for
445               1024 bytes).  Default is 'SI'.
446
447           Charset
448               Character set for encoding character tag values passed to/from
449               ExifTool with code points above U+007F.  Default is 'UTF8'.
450               Valid values are listed below, case is not significant:
451
452                 Value        Alias(es)        Description
453                 -----------  ---------------  ----------------------------------
454                 UTF8         cp65001, UTF-8   UTF-8 characters
455                 Latin        cp1252, Latin1   Windows Latin1 (West European)
456                 Latin2       cp1250           Windows Latin2 (Central European)
457                 Cyrillic     cp1251, Russian  Windows Cyrillic
458                 Greek        cp1253           Windows Greek
459                 Turkish      cp1254           Windows Turkish
460                 Hebrew       cp1255           Windows Hebrew
461                 Arabic       cp1256           Windows Arabic
462                 Baltic       cp1257           Windows Baltic
463                 Vietnam      cp1258           Windows Vietnamese
464                 Thai         cp874            Windows Thai
465                 DOSLatinUS   cp437            DOS Latin US
466                 DOSLatin1    cp850            DOS Latin1
467                 DOSCyrillic  cp866            DOS Cyrillic
468                 MacRoman     cp10000, Roman   Macintosh Roman
469                 MacLatin2    cp10029          Macintosh Latin2 (Central Europe)
470                 MacCyrillic  cp10007          Macintosh Cyrillic
471                 MacGreek     cp10006          Macintosh Greek
472                 MacTurkish   cp10081          Macintosh Turkish
473                 MacRomanian  cp10010          Macintosh Romanian
474                 MacIceland   cp10079          Macintosh Icelandic
475                 MacCroatian  cp10082          Macintosh Croatian
476
477               Note that this option affects some types of information when
478               reading/writing the file and other types when getting/setting
479               tag values, so it must be defined for both types of access.
480               See the "CHARACTER ENCODINGS" section for more information
481               about the handling of special characters.
482
483           CharsetEXIF
484               Internal encoding to use for stored EXIF "ASCII" string values.
485               May also be set to undef to pass through EXIF "ASCII" values
486               without recoding.  Set to "UTF8" to conform with the MWG
487               recommendation.  Default is undef.
488
489           CharsetFileName
490               External character set used for file names passed to ExifTool
491               functions.  When set in Windows, this triggers use of Windows
492               wide-character i/o library routines (requires Win32API::File).
493               Default is undef.  May also be set to an empty string to avoid
494               "encoding not specified" warnings on Windows.
495
496           CharsetID3
497               Internal encoding to assume for ID3v1 strings.  By the
498               specification ID3v1 strings should be encoded in ISO 8859-1
499               (essentially Latin), but some applications may use local
500               encoding instead.  Default is 'Latin'.
501
502           CharsetIPTC
503               Fallback internal IPTC character set to assume if IPTC
504               information contains no CodedCharacterSet tag.  Possible values
505               are the same as the "Charset" option.  Default is 'Latin'.
506
507               Note that this option affects some types of information when
508               reading/writing the file and other types when getting/setting
509               tag values, so it must be defined for both types of access.
510
511           CharsetPhotoshop
512               Internal encoding to assume for Photoshop IRB resource names.
513               Default is 'Latin'.
514
515           CharsetQuickTime
516               Internal encoding to assume for QuickTime strings stored with
517               an unspecified encoding.  Default is 'MacRoman'.
518
519           CharsetRIFF
520               Internal encoding to assume for strings in RIFF metadata (eg.
521               AVI and WAV files).  The default value of 0 assumes "Latin"
522               encoding unless otherwise specified by the RIFF CSET chunk.
523               Set to undef to pass through strings without recoding.  Default
524               is 0.
525
526           Compact
527               Comma-delimited list of settings for writing compact XMP.
528               Below is a list of available settings.  Note that 'NoPadding'
529               effects only embedded XMP since padding is never written for
530               stand-alone XMP files.  Also note that 'OneDesc' is not
531               recommended when writing XMP larger than 64 KiB to a JPG file
532               because it interferes with ExifTool's technique of splitting
533               off large rdf:Description elements into the extended XMP.  Case
534               is not significant for any of these options.  Aliases are given
535               in brackets. Default is undef.
536
537                 NoPadding - Avoid 2 KiB of recommended padding at end of XMP (NoPad)
538                 NoIndent  - No spaces to indent lines (NoSpace, NoSpaces)
539                 NoNewline - Avoid unnecessary newlines (NoNewlines)
540                 Shorthand - Use XMP Shorthand format
541                 OneDesc   - Combine properties into a single rdf:Description (OneDescr)
542                 AllSpace  - Equivalent to 'NoPadding,NoIndent,NoNewline'
543                 AllFormat - Equivalent to 'Shorthand,OneDesc'
544                 All       - Equivalent to 'AllSpace,AllFormat'
545
546           Composite
547               Flag to generate Composite tags when extracting information.
548               Default is 1.
549
550           Compress
551               Flag to write new values in compressed format if possible.  Has
552               no effect unless the relevant compression library is available.
553               Valid when writing metadata to PNG, JXL or MIE images.  Setting
554               this to zero causes JXL metadata to be rewritten as
555               uncompressed when edited.  Default is undef.
556
557           CoordFormat
558               Format for printing GPS coordinates.  This is a printf format
559               string with specifiers for degrees, minutes and seconds in that
560               order, however minutes and seconds may be omitted.  If the
561               hemisphere is known, a reference direction (N, S, E or W) is
562               appended to each printed coordinate, but adding a "+" to the
563               first format specifier (eg. "%+.6f") prints a signed coordinate
564               instead.  For example, the following table gives the output for
565               the same coordinate using various formats:
566
567                     CoordFormat        Example Output
568                 -------------------  ------------------
569                 q{%d deg %d' %.2f"}  54 deg 59' 22.80"  (default for reading)
570                 q{%d %d %.8f}        54 59 22.80000000  (default for copying)
571                 q{%d deg %.4f min}   54 deg 59.3800 min
572                 q{%.6f degrees}      54.989667 degrees
573
574               Note:  To avoid loss of precision, the default coordinate
575               format is different when copying tags with
576               "SetNewValuesFromFile".
577
578           DateFormat
579               Format for printing date/time values.  See "strftime" in the
580               POSIX package and <https://exiftool.org/filename.html#codes>
581               for details about the format string.  If the date can not be
582               converted, the value is left unchanged unless the StrictDate
583               option is set.  Timezones are ignored.  The inverse conversion
584               (ie. when calling "SetNewValue") is performed only if
585               POSIX::strptime or Time::Piece is installed.  The default
586               setting of undef causes date/time values to remain in standard
587               EXIF format (similar to a DateFormat of "%Y:%m:%d %H:%M:%S").
588
589           Duplicates
590               Flag to return values from tags with duplicate names when
591               extracting information.  Default is 1.
592
593           Escape
594               Escape special characters in extracted values for HTML or XML.
595               Also unescapes HTML or XML character entities in input values
596               passed to "SetNewValue".  Valid settings are 'HTML', 'XML' or
597               undef.  Default is undef.
598
599           Exclude
600               Exclude specified tags when extracting information.  Note that
601               this option is applied after all of the tags have already been
602               loaded into memory (so different tags may be excluded in
603               subsequent calls to "GetInfo"). See the IgnoreTags option to
604               save memory by not loading the tags in the first place.  The
605               option value is either a tag name or reference to a list of tag
606               names to exclude.  The case of tag names is not significant.
607               This option is ignored for specifically requested tags.  Tags
608               may also be excluded by preceding their name with a '-' in the
609               arguments to "ImageInfo".
610
611           ExtendedXMP
612               This setting affects the reading and editing of extended XMP in
613               JPEG images.  According to the XMP specification, extended XMP
614               is only valid if it has the GUID specified by the
615               HasExtendedXMP tag, so by default ExifTool will ignore other
616               extended XMP, but this option allows full control over the
617               extended XMP to be extracted.
618
619                    0   - Ignore all extended XMP
620                    1   - Read extended XMP with valid GUID only (default)
621                    2   - Read extended XMP with any GUID
622                 <guid> - Read extended XMP with a specific GUID
623
624           ExtractEmbedded
625               Flag to extract information from embedded documents in EPS
626               files, embedded EPS information and JPEG and Jpeg2000 images in
627               PDF files, embedded MPF images in JPEG and MPO files, metadata
628               after the first Cluster in MKV files, timed metadata in videos,
629               all frames of a multipart EXR image, and the resource fork of
630               Mac OS files. A setting of 2 also causes the H264 video stream
631               in MP4 files to be parsed until the first SEI message is
632               decoded, or 3 to parse the entire H264 stream in MP4 videos and
633               the entire M2TS file to look for any unlisted program
634               containing GPS metadata. Default is undef.
635
636           FastScan
637               Flag to increase speed when reading files by avoiding
638               extraction of some types of metadata.  With this option set to
639               1, ExifTool will not scan to the end of a JPEG image to check
640               for an AFCP, CanonVRD, FotoStation, PhotoMechanic, MIE or
641               PreviewImage trailer.  This also stops the parsing after the
642               first comment in GIF images, and at the audio/video data of
643               RIFF-format files (AVI, WAV, etc), so any trailing metadata
644               (eg. XMP written by some utilities) may be missed.  Also
645               disables input buffering for some types of files to reduce
646               memory usage when reading from a non-seekable stream, and
647               bypasses CRC validation for speed when writing PNG files.  When
648               combined with the ScanForXMP option, prevents scanning for XMP
649               in recognized file types.  With a value of 2, ExifTool will
650               also avoid extracting any EXIF MakerNote information, and will
651               stop processing at the IDAT chunk of PNG images and the mdat
652               atom in QuickTime-format files.  (By the PNG specification,
653               metadata is allowed after IDAT, but ExifTool always writes it
654               before because some utilities will ignore it otherwise.)  When
655               set to 3 or higher, only pseudo system tags and FileType are
656               generated. For 3, the file header is read to provide an
657               educated guess at FileType. For 4, the file is not read at all
658               and FileType is determined based on the file's extension.  For
659               5, generation of Composite tags is also disabled (like setting
660               "Composite" to 0).  Default is undef.
661
662           Filter
663               Perl expression used to filter values for all tags.  The
664               expression acts on the value of the Perl default variable ($_),
665               and changes the value of this variable as required.  The
666               current ExifTool object may be accessed through $self.  The
667               value is not changed if $_ is set to undef.  List items are
668               filtered individually.  Applies to all returned values unless
669               PrintConv option is disabled.
670
671           FilterW
672               Perl expression used to filter PrintConv values when writing.
673               The expression acts on the value of the Perl default variable
674               ($_), and changes the value of this variable as required.  The
675               current ExifTool object may be accessed through $self.  The tag
676               is not written if $_ is set to undef.
677
678           FixBase
679               Fix maker notes base offset.  A common problem with image
680               editing software is that offsets in the maker notes are not
681               adjusted properly when the file is modified.  This may cause
682               the wrong values to be extracted for some maker note entries
683               when reading the edited file.  FixBase specifies an integer
684               value to be added to the maker notes base offset.  It may also
685               be set to the empty string ('') for ExifTool will take its best
686               guess at the correct base, or undef (the default) for no base
687               adjustment.
688
689           GeoMaxIntSecs
690               Maximum interpolation time in seconds for geotagging.
691               Geotagging is treated as an extrapolation if the Geotime value
692               lies between two fixes in the same track which are separated by
693               a number of seconds greater than this.  Otherwise, the
694               coordinates are calculated as a linear interpolation between
695               the nearest fixes on either side of the Geotime value.  Set to
696               0 to disable interpolation and use the coordinates of the
697               nearest fix instead (provided it is within GeoMaxExtSecs,
698               otherwise geotagging fails).  Default is 1800.
699
700           GeoMaxExtSecs
701               Maximum extrapolation time in seconds for geotagging.
702               Geotagging fails if the Geotime value lies outside a GPS track
703               by a number of seconds greater than this.  Otherwise, for an
704               extrapolation the coordinates of the nearest fix are taken (ie.
705               it is assumed that you weren't moving during this period).
706               Default is 1800.
707
708           GeoMaxHDOP
709               Maximum Horizontal (2D) Dilution Of Precision for geotagging.
710               GPS fixes are ignored if the HDOP is greater than this.
711               Default is undef.
712
713           GeoMaxPDOP
714               Maximum Position (3D) Dilution Of Precision for geotagging.
715               GPS fixes are ignored if the PDOP is greater than this.
716               Default is undef.
717
718           GeoMinSats
719               Minimum number of satellites for geotagging.  GPS fixes are
720               ignored if the number of acquired satellites is less than this.
721               Default is undef.
722
723           GeoSpeedRef
724               Reference units for writing GPSSpeed when geotagging:
725
726                   'K', 'k' or 'km/h'  - km/h
727                   'M', 'm' or 'mph'   - mph
728                   <anything else>     - knots (default undef)
729
730           GlobalTimeShift
731               Time shift to apply to all extracted date/time PrintConv
732               values.  Does not affect ValueConv values.  Value is a
733               date/time shift string (see Image::ExifTool::Shift(3pm)), with
734               a leading '-' for negative shifts.  Default is undef.
735
736           Group#
737               Extract tags only for specified groups in family # (Group0
738               assumed if # not given).  The option value may be a single
739               group name or a reference to a list of groups.  Case is
740               significant in group names.  Specify a group to be excluded by
741               preceding group name with a '-'.  See "GetGroup" for a
742               description of group families, and "GetAllGroups [static]" for
743               lists of group names.
744
745           HexTagIDs
746               Return hexadecimal instead of decimal for the family 7 group
747               names of tags with numerical ID's.
748
749           HtmlDump
750               Dump information in hex to dynamic HTML web page.  The value
751               may be 0-3 for increasingly larger limits on the maximum block
752               size.  Default is 0.  Output goes to the file specified by the
753               TextOut option (\*STDOUT by default).
754
755           HtmlDumpBase
756               Base for HTML dump offsets.  If not defined, the EXIF/TIFF base
757               offset is used.  Set to 0 for absolute offsets.  Default is
758               undef.
759
760           IgnoreMinorErrors
761               Flag to ignore minor errors.  Causes minor errors to be
762               downgraded to warnings, and minor warnings to be ignored.  This
763               option is provided mainly to allow writing of files when minor
764               errors occur, but by ignoring some minor warnings the behaviour
765               of ExifTool may be changed to allow some questionable
766               operations to proceed (such as extracting thumbnail and preview
767               images even if they don't have a recognizable header).  Minor
768               errors and warnings are denoted by "[minor]" at the start of
769               the message, or "[Minor]" (with a capital "M") for warnings
770               that affect processing when ignored.
771
772           IgnoreTags
773               List of tag names to ignore when reading.  This may help in
774               situations where memory is limited because the ignored tag
775               values are not stored in memory.  The tag names are case
776               insensitive and group names and wildcards are not allowed.  A
777               special tag name of "All" may be used to ignore all tags except
778               those specified by the "RequestTags" option.  Set to undef to
779               clear the previous IgnoreTags list.  Default is undef.
780
781           ImageHashType
782               Sets type of hash algorithem used for the ImageDataHash tag
783               calculation.  Supported options are 'MD5', 'SHA256', and
784               'SHA512'.  Default is 'MD5'.
785
786           Lang
787               Localized language for exiftool tag descriptions, etc.
788               Available languages are given by the Image::ExifTool::Lang
789               module names (eg. 'fr', 'zh_cn').  If the specified language
790               isn't available, the option is not changed.  May be set to
791               undef to select the built-in default language.  Default is
792               'en'.
793
794           LargeFileSupport
795               Flag to indicate that 64-bit file offsets are supported on this
796               system.  Default is undef.
797
798           ListItem
799               Return only a specific item from list-type values.  A value of
800               0 returns the first item in the list, 1 return the second item,
801               etc.  Negative indices may also be used, with -1 representing
802               the last item in the list.  Applies only to the top-level list
803               of nested lists.  Default is undef to return all items in the
804               list.
805
806           ListJoin
807               Separator used to join the PrintConv value of multi-item List-
808               type tags into a single string.  If not defined, multi-item
809               lists are returned as a list reference.  Does not affect
810               ValueConv values.  Default is ', '.
811
812           ListSplit
813               Regular expression used to split values of list-type tags into
814               individual items when writing.  (eg. use ',\\s*' to split a
815               comma-separated list.)  Split when writing either PrintConv or
816               ValueConv values.  Default is undef.
817
818           MakerNotes
819               Option to extract MakerNotes and other writable subdirectories
820               (such as PrintIM) as a data block.  Normally when the
821               MakerNotes are extracted they are rebuilt to include data
822               outside the boundaries of the original maker note data block,
823               but a value of 2 disables this feature.  Possible values are:
824
825                 0 - Do not extract writable subdirectories (same as default of undef)
826                 1 - Extract and rebuild maker notes into self-contained block
827                 2 - Extract without rebuilding maker notes
828
829           MDItemTags
830               Flag to extract the OS X metadata item tags (see the "mdls" man
831               page and "MacOS MDItem Tags" in Image::ExifTool::TagNames for
832               more information).
833
834           MissingTagValue
835               Value for missing tags in tag name expressions (or tags where
836               the advanced formatting expression returns undef).  If not set,
837               a minor error is issued for missing values, or the value is set
838               to '' if "IgnoreMinorErrors" is set.  Default is undef.
839
840           NoDups
841               Flag to remove duplicate items from queued values for List-type
842               tags when writing.  This applies only to queued values, and
843               doesn't resolve duplicates with existing values in the file
844               when adding to an existing list.  Default is undef.
845
846           NoMultiExif
847               Raise error when attempting to write multi-segment EXIF in a
848               JPEG image.  Default is undef.
849
850           NoPDFList
851               Flag to avoid splitting PDF list-type tag values into separate
852               items.  Default is undef.
853
854           NoWarning[+]
855               Regular expression to suppress matching warning messages.  For
856               example, a value of "^Ignored" suppresses all warnings that
857               begin with the word "Ignored".  Has no other effect on
858               processing, unlike IgnoreMinorWarnings for some warnings.
859               Start the expression with "(?i)" for case-insensitive matching.
860               Use NoWarning+ to add to existing expressions.  Default is
861               undef.
862
863           Password
864               Password for reading/writing password-protected PDF documents.
865               Ignored if a password is not required.  Character encoding of
866               the password is determined by the value of the Charset option
867               at processing time.  Default is undef.
868
869           PrintConv
870               Flag to enable automatic print conversion.  Also enables
871               inverse print conversion for writing.  Default is 1.
872
873           QuickTimeHandler
874               Flag set to add an 'mdir' Handler to a newly created Meta box
875               when adding QuickTime ItemList tags.  Adobe Bridge does not add
876               this Handler, but it is commonly found in samples from other
877               software, and it has been reported that Apple QuickTime Player
878               and Photos.apps will ignore ItemList tags if this is missing.
879               Default is 1.
880
881           QuickTimePad
882               Flag to preserve the padding of some QuickTime atoms when
883               writing.  QuickTime-based Canon CR3 files pad the values of
884               container atoms with null bytes.  This padding is removed by
885               default when the file is rewritten, but setting this option to
886               1 adds padding to preserve the original atom size if the new
887               atom would be smaller than the original.  Default is undef.
888
889           QuickTimeUTC
890               Flag set to assume that QuickTime date/time values are stored
891               as UTC, causing conversion to local time when they are
892               extracted and from local time when written.  According to the
893               QuickTime specification date/time values should be UTC, but
894               many digital cameras store local time instead (presumably
895               because they don't know the time zone), so the default is to
896               not convert these times (except for Canon CR3 files, which
897               always use UTC times).  This option also disables the
898               autodetection of incorrect time-zero offsets in QuickTime
899               date/time values, and enforces a time zero of 1904 as per the
900               QuickTime specification.
901
902           RequestAll
903               Flag to request all tags to be extracted.  This causes some
904               tags to be generated which normally would not be unless
905               specifically requested (by passing the tag name to "ImageInfo"
906               or "ExtractInfo").  May be set to 2 or 3 to enable generation
907               of some additional tags as mentioned in the tag name
908               documentation.  Default is undef.
909
910           RequestTags
911               List of additional tag and/or group names to request in the
912               next call to "ExtractInfo".  This option is useful only for
913               tags/groups which aren't extracted unless specifically
914               requested.  Value may be a list reference, a delimited string
915               of names (any delimiter is allowed), or undef to clear the
916               current RequestTags list.  Groups are requested by adding a
917               colon after the name (eg. "MacOS:").  Names are converted to
918               lower case as they are added to the list.  Default is undef.
919
920           SaveFormat
921               Flag to save EXIF/TIFF format type as the family 6 group name
922               when extracting information.  Without this option set, the
923               family 6 group names are not generated.  Default is undef.  See
924               the "GetGroup" option for more details.
925
926           SavePath
927               Flag to save the metadata path as the family 5 group name when
928               extracting information.  Without this option set, the family 5
929               group names are not generated.  Default is undef.  See the
930               "GetGroup" option for more details.
931
932           ScanForXMP
933               Flag to scan all files (even unrecognized formats) for XMP
934               information unless XMP was already found in the file.  When
935               combined with the FastScan option, only unrecognized file types
936               are scanned for XMP.  Default is undef.
937
938           Sort
939               Specifies order to sort tags in returned list:
940
941                 Input  - Sort in same order as input tag arguments (default)
942                 File   - Sort in order that tags were found in the file
943                 Tag    - Sort alphabetically by tag name
944                 Descr  - Sort by tag description (for current Lang setting)
945                 Group# - Sort by tag group, where # is zero or more family
946                          numbers separated by colons. If # is not specified,
947                          Group0 is assumed.  See GetGroup for a description
948                          of group families.
949
950           Sort2
951               Secondary sort order used for tags within each group when Sort
952               is 'Group':
953
954                 File   - Sort in order tags were found in the file (default)
955                 Tag    - Sort alphabetically by tag name
956                 Descr  - Sort by tag description (for current Lang setting)
957
958           StrictDate
959               Flag to return undefined value for any date which can't be
960               converted when the DateFormat option is used.  Default is
961               undef.
962
963                 undef - Same as 0 for reading/writing, or 1 for copying
964                   0   - Return date/time value unchanged if it can't be converted
965                   1   - Return undef if date/time value can't be converted
966
967               When set to 1 while writing a PrintConv date/time value with
968               the DateFormat option set, the value is written only if
969               POSIX::strptime or Time::Piece is available and can
970               successfully convert the value.
971
972               For PNG CreationTime, a setting of 1 has the additional effect
973               of causing the date/time to be reformatted according to PNG 1.2
974               recommendation (RFC-1123) when writing, and a warning to be
975               issued for any non-standard value when reading (but note that
976               Windows may not recognize PNG date/time values in standard
977               format).
978
979           Struct
980               Flag to return XMP structures as hash references instead of
981               flattening into individual tags.  Has no effect when writing
982               since both flattened and structured tags may always be written.
983               Possible values are:
984
985                 undef - (default) Same as 0 for reading, 2 for copying
986                   0   - Read/copy flattened tags
987                   1   - Read/copy structured tags
988                   2   - Read/copy both flattened and structured tags, but flag
989                         flattened tags as 'unsafe' for copying
990
991           StructFormat
992               Format for serialized structures when reading/writing.
993
994                 undef - Default ExifTool format
995                 JSON  - JSON format
996                 JSONQ - JSON with quoted numerical values
997
998           SystemTags
999               Flag to extract the following additional File System tags:
1000               FileAttributes, FileDeviceNumber, FileInodeNumber,
1001               FileHardLinks, FileUserID, FileGroupID, FileDeviceID,
1002               FileBlockSize and FileBlockCount.
1003
1004           TextOut
1005               Output file reference for Verbose and HtmlDump options.
1006               Default is \*STDOUT.
1007
1008           TimeZone
1009               Time zone for local date/time values.  May be set to any valid
1010               TZ string.  Uses the system time zone if not specified.
1011               Default is undef.  (Requires POSIX::tzset, which may not be
1012               available in Windows.  A work-around in Windows is to "set
1013               TZ=<zone>" before running ExifTool.)
1014
1015           Unknown
1016               Flag to get the values of unknown tags.  If set to 1, unknown
1017               tags are extracted from EXIF (or other tagged-format)
1018               directories.  If set to 2, unknown tags are also extracted from
1019               binary data blocks.  Default is 0.
1020
1021           UserParam
1022               Special option to set/get user-defined parameters.  Useful to
1023               allow external input into tag name expressions and ValueConv
1024               logic.  Valid UserParam values are:
1025
1026                 PARAM         - Get parameter
1027                 PARAM=        - Clear parameter
1028                 PARAM^=       - Set parameter to empty string
1029                 PARAM=VALUE   - Set parameter
1030                 <hash ref>    - Set entire UserParam hash lookup
1031                 undef         - Clear all user parameters
1032
1033               Where PARAM is the user-defined parameter name (case
1034               insensitive).
1035
1036               User-defined parameters may be accessed in tag name expressions
1037               by prefixing the parameter name with a dollar sign just like
1038               normal tags, or via the API by calling
1039               "Options('UserParam','PARAM')".  Appending a hash tag ("#") to
1040               the parameter name also causes the parameter to be extracted as
1041               a normal tag (in the UserParam group).  If called without
1042               additional arguments, Options('UserParam') returns a reference
1043               to the hash of all user parameters (with lower-case names).
1044
1045           Validate
1046               Flag to perform extra validation metadata checks when reading,
1047               causing extra warnings to be generated if problems are found.
1048               Default is undef.
1049
1050           Verbose
1051               Print verbose messages to file specified by TextOut option.
1052               Value may be from 0 to 5 for increasingly verbose messages.
1053               Default is 0.  With the verbose option set, messages are
1054               printed to the console as the file is parsed.  Level 1 prints
1055               the tag names and raw values.  Level 2 adds more details about
1056               the tags.  Level 3 adds a hex dump of the tag data, but with
1057               limits on the number of bytes dumped.  Levels 4 and 5 remove
1058               the dump limit on tag values and JPEG segment data
1059               respectively.
1060
1061           WindowsWideFile
1062               Force the use of wide-character Windows I/O functions when the
1063               "CharsetFileName" option is used.  This may be necessary when
1064               files are on a network drive and the current directory name
1065               contains Unicode characters.  By default, the wide-character
1066               functions are used only if the specified file path contains
1067               Unicode characters.
1068
1069           WriteMode
1070               Set tag write/create mode.  Value is a string of one or more
1071               characters from list below.  Default is 'wcg'.
1072
1073                   w - Write existing tags
1074                   c - Create new tags
1075                   g - create new Groups as necessary
1076
1077               The level of the group differs for different types of metadata.
1078               For XMP or IPTC this is the full XMP/IPTC block (the family 0
1079               group), but for EXIF this is the individual IFD (the family 1
1080               group).  The 'w' and 'c' modes are tested only when
1081               "SetNewValue" is called, but the 'g' mode is also tested in
1082               "WriteInfo".
1083
1084           XAttrTags
1085               Flag to extract the OS X extended attribute tags (see the
1086               "xattr" man page and "MacOS XAttr Tags" in
1087               Image::ExifTool::TagNames for more information).
1088
1089           XMPAutoConv
1090               Flag to enable automatic conversion for unknown XMP tags with
1091               values that look like rational numbers or dates.  Default is 1.
1092
1093       Return Values:
1094           The original value of the last specified parameter.
1095
1096   ClearOptions
1097       Reset all options to their default values.  Loads user-defined default
1098       option values from the %Image::ExifTool::UserDefined::Options hash in
1099       the .ExifTool_config file if it exists.
1100
1101           $exifTool->ClearOptions();
1102
1103       Inputs:
1104           0) ExifTool object reference
1105
1106       Return Values:
1107           (none)
1108
1109   ExtractInfo
1110       Extract all meta information from an image.
1111
1112           $success = $exifTool->ExtractInfo('image.jpg', \%options);
1113
1114       Inputs:
1115           "ExtractInfo" takes exactly the same arguments as "ImageInfo".  The
1116           only difference is that a list of tag keys is not returned if an
1117           ARRAY reference is given.  The following options are effective in
1118           the call to "ExtractInfo":
1119
1120           Binary, Charset, CharsetEXIF, CharsetFileName, CharsetID3,
1121           CharsetIPTC, CharsetPhotoshop, CharsetQuickTime, CharsetRIFF,
1122           Composite, ExtendedXMP, ExtractEmbedded, FastScan, FixBase,
1123           HtmlDump, HtmlDumpBase, IgnoreMinorErrors, IgnoreTags, Lang,
1124           LargeFileSupport, MakerNotes, MDItemTags, NoPDFList, Password,
1125           QuickTimeUTC (enforced 1904 time zero), RequestAll, RequestTags,
1126           SaveFormat, SavePath, ScanForXMP, Struct, TextOut, Unknown,
1127           Verbose, WindowsWideFile, XAttrTags and XMPAutoConv.
1128
1129       Return Value:
1130           1 if this was a recognized file format, 0 otherwise (and 'Error'
1131           tag set).
1132
1133   GetInfo
1134       "GetInfo" is called to return meta information after it has been
1135       extracted from the image by a previous call to "ExtractInfo" or
1136       "ImageInfo". This function may be called repeatedly after a single call
1137       to "ExtractInfo" or "ImageInfo".
1138
1139           # get image width and height only
1140           $info = $exifTool->GetInfo('ImageWidth', 'ImageHeight');
1141
1142           # get all Error and Warning messages
1143           $info = $exifTool->GetInfo('Error', 'Warning');
1144
1145           # get information for all tags in list (list updated with tags found)
1146           $info = $exifTool->GetInfo(\@ioTagList);
1147
1148           # get all information in Author or Location groups
1149           $info = $exifTool->GetInfo({Group2 => ['Author', 'Location']});
1150
1151       Inputs:
1152           Inputs are the same as "ExtractInfo" and "ImageInfo" except that an
1153           image can not be specified.  Options in effect are:
1154
1155           Charset, CoordFormat, DateFormat, Duplicates, Escape, Exclude,
1156           Filter, Group#, GlobalTimeShift, Lang, ListItem, ListJoin,
1157           PrintConv, Sort (if a tag list reference is given) and StrictDate.
1158
1159       Return Value:
1160           Reference to information hash, the same as with "ImageInfo".
1161
1162       The following options are effective in the call to "GetInfo":
1163
1164       Charset, CoordFormat, DateFormat, Duplicates, Escape, Exclude, Filter,
1165       Group#, GlobalTimeShift, Lang, ListItem, ListJoin, PrintConv,
1166       QuickTimeUTC (conversion to local time), Sort (if a tag list reference
1167       is given) and StrictDate.
1168
1169   WriteInfo
1170       Write meta information to a file.  The specified source file is
1171       rewritten to the same-type destination file with new information as
1172       specified by previous calls to "SetNewValue".  The necessary segments
1173       and/or directories are created in the destination file as required to
1174       store the specified information.  May be called repeatedly to write the
1175       same information to additional files without the need to call
1176       "SetNewValue" again.
1177
1178       ExifTool queues all new values that are assigned via calls to
1179       "SetNewValue", then applies them to any number of files through one or
1180       more calls to "WriteInfo". These queued values may be accessed through
1181       "GetNewValue", and are completely separate from metadata extracted from
1182       files via "ExtractInfo" or "ImageInfo" and accessed through "GetInfo"
1183       or "GetValue".
1184
1185       To be clear, it is NOT necessary to call "ExtractInfo" or "ImageInfo"
1186       before "WriteInfo".  "WriteInfo" changes only metadata specified by
1187       previous calls to "SetNewValue".
1188
1189           # add information to a source file, writing output to new file
1190           $exifTool->WriteInfo($srcfile, $dstfile);
1191
1192           # create XMP data file from scratch
1193           $exifTool->WriteInfo(undef, $dstfile, 'XMP');
1194
1195           # overwrite file (you do have backups, right?)
1196           $exifTool->WriteInfo($srcfile);
1197
1198       Inputs:
1199           0) ExifTool object reference
1200
1201           1) Source file name, file reference, scalar reference, or undef to
1202           create a file from scratch.  A reference to a File::RandomAccess
1203           object is also allowed as a source, but in this case the
1204           destination is not optional.
1205
1206           2) [optional] Destination file name, file reference, scalar
1207           reference to write to memory, or undef to overwrite the original
1208           file.  May be '-' to write to stdout.
1209
1210           3) [optional] Destination file type.  Ignored if a source is
1211           defined.
1212
1213       Return Value:
1214           1 if file was written OK, 2 if file was written but no changes
1215           made, 0 on file write error.
1216
1217           If an error code is returned, an Error tag is set and
1218           GetValue('Error') can be called to obtain the error description.  A
1219           Warning tag may be set even if this routine is successful.  Calling
1220           WriteInfo clears any pre-existing Error and Warning tags.
1221
1222               $errorMessage = $exifTool->GetValue('Error');
1223               $warningMessage = $exifTool->GetValue('Warning');
1224
1225       Notes:
1226           The source file name may be undefined to create a file from scratch
1227           (currently only XMP, MIE, ICC, VRD, DR4, EXV and EXIF files can be
1228           created in this way -- see "CanCreate" for details).  If undefined,
1229           the destination file type is required unless the type can be
1230           determined from the extension of the destination file name.
1231
1232           If a destination file name is given, the specified file must not
1233           exist because an existing destination file will not be overwritten.
1234           Any new values for FileName, Directory or HardLink are ignored when
1235           a destination file name is specified.
1236
1237           The destination file name may be undefined to overwrite the
1238           original file (make sure you have backups!).  In this case, if a
1239           source file name is provided, a temporary file is created and
1240           renamed to replace the source file if no errors occurred while
1241           writing.  Otherwise, if a source file reference or scalar reference
1242           is used, the image is first written to memory then copied back to
1243           replace the original if there were no errors.
1244
1245           On Mac OS systems, the file resource fork is preserved if this
1246           routine is called with a source file name.
1247
1248       The following ExifTool options are effective in the call to
1249       "WriteInfo":
1250
1251       ByteOrder, Charset, CharsetEXIF, CharsetFileName, CharsetIPTC, Compact,
1252       Compress, FixBase, IgnoreMinorErrors, NoMultiExif, NoPDFList, Password,
1253       QuickTimeHandler, QuickTimePad, Verbose, WindowsWideFile and WriteMode.
1254
1255   GetTagList
1256       Get a sorted list of tags from the specified information hash or tag
1257       list.
1258
1259           @tags = $exifTool->GetTagList($info, 'Group0');
1260
1261       Inputs:
1262           0) ExifTool object reference
1263
1264           1) [optional] Information hash reference or tag list reference
1265
1266           2) [optional] Sort order ('Input', 'File', 'Tag', 'Descr' or
1267           'Group#')
1268
1269           3) [optional] Secondary sort order ('File', 'Tag' or 'Descr')
1270
1271           If the information hash or tag list reference is not provided, then
1272           the list of found tags from the last call to "ImageInfo",
1273           "ExtractInfo" or "GetInfo" is used instead, and the result is the
1274           same as if "GetFoundTags" was called.  If sort order is not
1275           specified, the sort order is taken from the current options
1276           settings.
1277
1278       Return Values:
1279           A list of tag keys in the specified order.
1280
1281   GetFoundTags
1282       Get list of found tags in specified sort order.  The found tags are the
1283       tags for the information obtained from the most recent call to
1284       "ImageInfo", "ExtractInfo" or "GetInfo" for this object.
1285
1286           @tags = $exifTool->GetFoundTags('File');
1287
1288       Inputs:
1289           0) ExifTool object reference
1290
1291           1) [optional] Sort order ('Input', 'File', 'Tag', 'Descr' or
1292           'Group#')
1293
1294           2) [optional] Secondary sort order ('File', 'Tag' or 'Descr')
1295
1296           If sort order is not specified, the sort order from the ExifTool
1297           options is used.
1298
1299       Return Values:
1300           A list of tag keys in the specified order.
1301
1302   GetRequestedTags
1303       Get list of requested tags.  These are the tags that were specified in
1304       the arguments of the most recent call to "ImageInfo", "ExtractInfo" or
1305       "GetInfo", including tags specified via a tag list reference. Shortcut
1306       tags are expanded in the list.
1307
1308           @tags = $exifTool->GetRequestedTags();
1309
1310       Inputs:
1311           (none)
1312
1313       Return Values:
1314           List of requested tag keys in the same order that the tags were
1315           specified.  Note that this list will be empty if tags were not
1316           specifically requested (ie. If extracting all tags).
1317
1318   GetValue
1319       Get the value of a specified tag.  The returned value is either the
1320       human-readable (PrintConv) value, the converted machine-readable
1321       (ValueConv) value, the original raw (Raw) value, or the original
1322       rational (Rational) value for rational formats.  If the value type is
1323       not specified, the PrintConv value is returned if the PrintConv option
1324       is set, otherwise the ValueConv value is returned.  The PrintConv
1325       values are same as the values returned by "ImageInfo" and "GetInfo" in
1326       the tag/value hash unless the PrintConv option is disabled.
1327
1328       Tags which represent lists of multiple values (as may happen with
1329       'Keywords' for example) are handled specially.  In scalar context, the
1330       returned PrintConv value for these tags is either a string of values or
1331       a list reference (depending on the ListJoin option setting), and the
1332       ValueConv value is always a list reference.  But in list context,
1333       "GetValue" always returns the list itself.
1334
1335       Note that "GetValue" requires a case-sensitive tag key as an argument.
1336       To retrieve tag information based on a case-insensitive tag name (with
1337       an optional group specifier), use "GetInfo" instead.
1338
1339           # PrintConv example
1340           my $val = $exifTool->GetValue($tag);
1341           if (ref $val eq 'SCALAR') {
1342               print "$tag = (unprintable value)\n";
1343           } else {
1344               print "$tag = $val\n";
1345           }
1346
1347           # ValueConv examples
1348           my $val = $exifTool->GetValue($tag, 'ValueConv');
1349           if (ref $val eq 'ARRAY') {
1350               print "$tag is a list of values\n";
1351           } elsif (ref $val eq 'SCALAR') {
1352               print "$tag represents binary data\n";
1353           } else {
1354               print "$tag is a simple scalar\n";
1355           }
1356
1357           my @keywords = $exifTool->GetValue('Keywords', 'ValueConv');
1358
1359       The following options are in effect when "GetValue" is called:
1360
1361       Charset, CoordFormat, DateFormat, Escape, Filter, GlobalTimeShift,
1362       Lang, ListItem, ListJoin, PrintConv, QuickTimeUTC (conversion to local
1363       time), StrictDate and TimeZone.
1364
1365       Inputs:
1366           0) ExifTool object reference
1367
1368           1) Tag key, or case-sensitive tag name with optional group
1369           prefix(es)
1370
1371           2) [optional] Value type: 'PrintConv', 'ValueConv', 'Both', 'Raw'
1372           or 'Rational'
1373
1374           The default value type is 'PrintConv' if the PrintConv option is
1375           set, otherwise the default is 'ValueConv'.  A value type of 'Both'
1376           returns both ValueConv and PrintConv values as a list.  'Rational'
1377           returns the raw rational value as a string fraction for rational
1378           types, or undef for other types.
1379
1380       Return Values:
1381           The value of the specified tag.  If the tag represents a list of
1382           multiple values and the ListJoin option is enabled then PrintConv
1383           returns a string of values, otherwise a reference to the list is
1384           returned in scalar context. The list itself is returned in list
1385           context.  (Unless 'Both' values are requested, in which case two
1386           list references are returned, regardless of context.)  Values may
1387           also be scalar references to binary data, or hash references if the
1388           "Struct" option is set.
1389
1390           Note: It is possible for "GetValue" to return an undefined
1391           ValueConv or PrintConv value (or an empty list in list context)
1392           even if the tag exists, since it is possible for these conversions
1393           to yield undefined values.  And the Rational value will be
1394           undefined for any non-rational tag.  The Raw value should always
1395           exist if the tag exists.
1396
1397   SetNewValue
1398       Set the new value for a tag.  The routine may be called multiple times
1399       to set the values of many tags before using "WriteInfo" to write the
1400       new values to an image.  These values remain queued for writing to
1401       subsequent files until "SetNewValue" is called without arguments to
1402       reset the queued values.
1403
1404       For list-type tags (like Keywords), either call repeatedly with the
1405       same tag name for each value, or call with a reference to the list of
1406       values.
1407
1408           # set a new value for a tag (errors go to STDERR)
1409           $success = $exifTool->SetNewValue($tag, $value);
1410
1411           # set a new value and capture any error message
1412           ($success, $errStr) = $exifTool->SetNewValue($tag, $value);
1413
1414           # delete information for specified tag if it exists in image
1415           # (also resets AddValue and DelValue options for this tag)
1416           $exifTool->SetNewValue($tag);
1417
1418           # reset all values from previous calls to SetNewValue()
1419           $exifTool->SetNewValue();
1420
1421           # delete a specific keyword
1422           $exifTool->SetNewValue('Keywords', $word, DelValue => 1);
1423
1424           # set keywords (a list-type tag) with two new values
1425           $exifTool->SetNewValue(Keywords => 'word1');
1426           $exifTool->SetNewValue(Keywords => 'word2');
1427           # equivalent, but set both in one call using an array reference
1428           $exifTool->SetNewValue(Keywords => ['word1','word2']);
1429
1430           # add a keyword without replacing existing keywords in the file
1431           $exifTool->SetNewValue(Keywords => $word, AddValue => 1);
1432
1433           # conditionally add a tag if it didn't exist before,
1434           # or replace it if it had a specified value ("old value")
1435           $exifTool->SetNewValue(Description => '', DelValue => 1);
1436           $exifTool->SetNewValue(Description => 'old value', DelValue => 1);
1437           $exifTool->SetNewValue(Description => 'new value');
1438
1439           # set a tag in a specific group
1440           $exifTool->SetNewValue(Headline => $val, Group => 'XMP');
1441           $exifTool->SetNewValue('XMP:Headline' => $val);  # (equivalent)
1442
1443           # shift original date/time back by 2.5 hours
1444           $exifTool->SetNewValue(DateTimeOriginal => '2:30', Shift => -1);
1445
1446           # write a tag only if it had a specific value
1447           # (the order of the following calls is not significant)
1448           $exifTool->SetNewValue(Title => $oldVal, DelValue => 1);
1449           $exifTool->SetNewValue(Title => $newVal);
1450
1451           # write tag by numerical value
1452           $exifTool->SetNewValue(Orientation => 6, Type => 'ValueConv');
1453           $exifTool->SetNewValue('Orientation#' => 6);  # (equivalent)
1454
1455           # delete all but EXIF tags
1456           $exifTool->SetNewValue('*');  # delete all...
1457           $exifTool->SetNewValue('EXIF:*', undef, Replace => 2); # ...but EXIF
1458
1459           # write structured information as a HASH reference
1460           $exifTool->SetNewValue('XMP:Flash' => {
1461               mode   => 'on',
1462               fired  => 'true',
1463               return => 'not'
1464           });
1465
1466           # write structured information as a serialized string
1467           $exifTool->SetNewValue('XMP:Flash'=>'{mode=on,fired=true,return=not}');
1468
1469       (See <https://exiftool.org/struct.html#Serialize> for a description of
1470       the structure serialization technique.)
1471
1472       Inputs:
1473           0) ExifTool object reference
1474
1475           1) [optional] Tag key or tag name, or undef to clear all new
1476           values.  The tag name may be prefixed by one or more family 0, 1 or
1477           2 group names with optional leading family numbers, separated by
1478           colons (eg. 'EXIF:Artist', 'XMP:Time:*'), which is equivalent to
1479           using a Group option argument.  Also, a '#' may be appended to the
1480           tag name (eg. 'EXIF:Orientation#'), with the same effect as setting
1481           Type to 'ValueConv'.  Wildcards ('*' and '?') may be used in the
1482           tag name to assign or delete multiple tags simultaneously.  A tag
1483           name of '*' is special when deleting information, and will delete
1484           an entire group even if some individual tags in the group are not
1485           writable, but only if a single family 0 or 1 group is specified
1486           (otherwise the tags are deleted individually).  Use
1487           "GetDeleteGroups" to get a list of deletable group names, and see
1488           Image::ExifTool::TagNames for a complete list of tag names.
1489
1490           2) [optional] New value for tag.  Undefined to delete tag from
1491           file.  May be a scalar, scalar reference, list reference to set a
1492           list of values, or hash reference for a structure.  Integer values
1493           may be specified as a hexadecimal string (with a leading '0x'), and
1494           simple rational values may be specified in fractional form (eg.
1495           '4/10').  Structure tags may be specified either as a hash
1496           reference or a serialized string (see the last two examples above).
1497
1498           3-N) [optional] SetNewValue option/value pairs (see below).
1499
1500       SetNewValue Options:
1501           AddValue
1502               Specifies that the value be added to an existing list in a file
1503               rather than overwriting the existing values.  Valid settings
1504               are 0 (overwrite any existing tag value), 1 (add to an existing
1505               list and warn for non-list tags) or 2 (add to existing list and
1506               overwrite non-list tags).  Default is 0.
1507
1508           DelValue
1509               Delete existing tag from a file if it has the specified value.
1510               For list-type tags this deletes a specified item from the list.
1511               For non-list tags this may be used to conditionally replace a
1512               tag by providing a new value in a separate call to SetNewValue
1513               (see examples above).  For structured tags, the entire
1514               structure is deleted/replaced only if all of the specified
1515               fields match the existing structure.  Option values are 0 or 1.
1516               Default is 0.
1517
1518           EditGroup
1519               Create tags in existing groups only.  Don't create new group.
1520               Valid values are 0 and 1.  Effectively removes the 'g' from the
1521               ExifTool WriteMode option for this tag only.  Default is 0.
1522
1523           EditOnly
1524               Edit tag only if it already exists.  Don't create new tag.
1525               Valid values are 0 and 1.  Effectively removes the 'c' from the
1526               ExifTool WriteMode option for this tag only.  Default is 0.
1527
1528           Group
1529               Specifies group name where tag should be written.  This option
1530               is superseded by any group specified in the tag name.  If not
1531               specified, tag is written to highest priority group as
1532               specified by "SetNewGroups".  May be one or more family 0, 1 or
1533               2 groups with optional leading family number, separated by
1534               colons.  Case is not significant.
1535
1536           NoFlat
1537               Treat flattened tags as 'unsafe'.
1538
1539           NoShortcut
1540               Disables default behaviour of looking up tag in shortcuts if
1541               not found otherwise.
1542
1543           Protected
1544               Bit mask for tag protection levels to write.  Bit 0x01 allows
1545               writing of 'unsafe' tags (ie. tags not copied automatically via
1546               "SetNewValuesFromFile").  Bit 0x02 allows writing of
1547               'protected' tags, and should only be used internally by
1548               ExifTool.  See Image::ExifTool::TagNames, for a list of tag
1549               names indicating 'unsafe' and 'protected' tags.  Default is 0.
1550
1551           ProtectSaved
1552               Avoid setting new values which were saved after the Nth call to
1553               "SaveNewValues".  Has no effect on unsaved values, or values
1554               saved before Nth call.  Option value is N.  Default is undef.
1555
1556           Replace
1557               Flag to replace the previous new values for this tag (ie.
1558               replace the values set in previous calls to "SetNewValue").
1559               This option is most commonly used to replace previously-set new
1560               values for list-type tags.  Valid values are 0 (set new value
1561               normally -- adds to new values for list-type tags), 1 (reset
1562               any previous new values before setting new value) or 2 (reset
1563               previous new values only; new value argument is ignored).
1564               Default is 0.
1565
1566           Shift
1567               Shift the tag by the specified value.  Currently only date/time
1568               tags and tags with numerical values may be shifted.  Undefined
1569               for no shift, 1 for a positive shift, or -1 for a negative
1570               shift.  A value of 0 causes a positive shift to be applied if
1571               the tag is shiftable and AddValue is set, or a negative shift
1572               for date/time tags only if DelValue is set. Default is undef.
1573               See Image::ExifTool::Shift(3pm) for more information.
1574
1575           Type
1576               The type of value being set.  Valid values are PrintConv,
1577               ValueConv or Raw.  Default is PrintConv if the "PrintConv"
1578               Option is set, otherwise ValueConv.
1579
1580       Return Values:
1581           In scalar context, returns the number of tags set and error
1582           messages are printed to STDERR.  In list context, returns the
1583           number of tags set, and the error string (which is undefined if
1584           there was no error).
1585
1586       Notes:
1587           When deleting groups of tags, the Replace option may be used to
1588           exclude specific groups from a mass delete.  However, this
1589           technique may not be used to exclude individual tags from a group
1590           delete (unless a family 2 group was specified in the delete).
1591           Instead, use "SetNewValuesFromFile" to recover the values of
1592           individual tags after deleting a group.
1593
1594           When deleting all tags from a JPEG image, the APP14 "Adobe"
1595           information is not deleted by default because doing so may affect
1596           the appearance of the image.  However, this information may be
1597           deleted by specifying it explicitly, either by group (with
1598           'Adobe:*') or as a block (with 'Adobe').
1599
1600       The following ExifTool options are effective in the call to
1601       "SetNewValue":
1602
1603       Charset, DateFormat, Escape, IgnoreMinorErrors, Lang, ListJoin,
1604       ListSplit, PrintConv, QuickTimeUTC, StrictDate, TimeZone, Verbose and
1605       WriteMode.
1606
1607   GetNewValue
1608       Get the new Raw value for a tag.  This is the value set by
1609       "SetNewValue" this is queued to be written to file.  List-type tags may
1610       return multiple values in list context.
1611
1612           $rawVal = $exifTool->GetNewValue($tag);
1613
1614           @rawVals = $exifTool->GetNewValue($tag);
1615
1616       Notes:
1617           The API NoDups option applies when this routine is called, and
1618           removes duplicate items from values returned for List-type tags.
1619
1620       Inputs:
1621           0) ExifTool object reference
1622
1623           1) Tag name (case sensitive, may be prefixed by family 0, 1 or 7
1624           group names, separated by colons)
1625
1626       Return Values:
1627           List of new Raw tag values, or first value in list when called in
1628           scalar context.  The list may be empty either if the tag isn't
1629           being written, or if it is being deleted (ie. if "SetNewValue" was
1630           called without a value).
1631
1632   SetNewValuesFromFile
1633       A very powerful routine that sets new values for tags from information
1634       found in a specified file.
1635
1636           # set new values from all information in a file...
1637           my $info = $exifTool->SetNewValuesFromFile($srcFile);
1638           # ...then write these values to another image
1639           my $result = $exifTool->WriteInfo($file2, $outFile);
1640
1641           # set all new values, preserving original groups
1642           $exifTool->SetNewValuesFromFile($srcFile, '*:*');
1643
1644           # set specific information
1645           $exifTool->SetNewValuesFromFile($srcFile, @tags);
1646
1647           # set new value from a different tag in specific group
1648           $exifTool->SetNewValuesFromFile($fp, 'XMP-dc:Subject<IPTC:Keywords');
1649
1650           # add all IPTC keywords to XMP subject list
1651           $exifTool->SetNewValuesFromFile($fp, 'XMP-dc:Subject+<IPTC:Keywords');
1652
1653           # set new value from an expression involving other tags
1654           $exifTool->SetNewValuesFromFile($file,
1655               'Comment<ISO=$ISO Aperture=$aperture Exposure=$shutterSpeed');
1656
1657           # set keywords list from the values of multiple tags
1658           $exifTool->SetNewValuesFromFile($file, { Replace => 0 },
1659               'keywords<xmp:subject', 'keywords<filename');
1660
1661           # copy all EXIF information, preserving the original IFD
1662           # (without '*.*<' tags would be copied to the preferred EXIF IFD)
1663           $exifTool->SetNewValuesFromFile($file, '*:*<EXIF:*');
1664
1665           # copy all tags with names starting with "gps" (note: this is
1666           # different than "gps:*" because it will also copy XMP GPS tags)
1667           $exifTool->SetNewValuesFromFile($file, 'gps*');
1668
1669           # set FileName from Model, translating questionable characters
1670           $exifTool->SetNewValuesFromFile($file,
1671               'filename<${model; tr(/\\\\?*:|"><)(_) }.jpg');
1672
1673       Inputs:
1674           0) ExifTool object reference
1675
1676           1) File name, file reference, or scalar reference
1677
1678           2-N) [optional] List of tag names to set or options hash
1679           references.  All writable tags are set if none are specified.  The
1680           tag names are not case sensitive, and may be prefixed by one or
1681           more family 0, 1, 2 or 7 group names with optional leading family
1682           numbers, separated by colons (eg.  'exif:iso'). A leading '-'
1683           indicates tags to be excluded (eg. '-comment'), or a trailing '#'
1684           causes the ValueConv value to be copied (same as setting the Type
1685           option to 'ValueConv' for this tag only).  A leading '+' sets the
1686           Replace option to 0 on a per-tag basis (see Options below).
1687           Wildcards ('*' and '?') may be used in the tag name.  A tag name of
1688           '*' is commonly used when a group is specified to copy all tags in
1689           the group (eg. 'XMP:*').  A special feature allows tag names of the
1690           form 'DSTTAG<SRCTAG' (or 'SRCTAG>DSTTAG') to be specified to copy
1691           information to a tag with a different name or a specified group.
1692           Both 'SRCTAG' and 'DSTTAG' may contain wildcards and/or be prefixed
1693           by a group name (eg.  'fileModifyDate<modifyDate' or 'xmp:*<*'),
1694           and/or suffixed by a '#' to disable print conversion.  Copied tags
1695           may also be added or deleted from a list with arguments of the form
1696           'DSTTAG+<SRCTAG' or 'DSTTAG-<SRCTAG'.  Tags are evaluated in order,
1697           so exclusions apply only to tags included earlier in the list.  An
1698           extension of this feature allows the tag value to be set from a
1699           string containing tag names with leading '$' symbols (eg.
1700           'Comment<the file is $filename'). Braces '{}' may be used around
1701           the tag name to separate it from subsequent text, and a '$$' is
1702           used to to represent a '$' symbol.  The behaviour for missing tags
1703           in expressions is defined by the "MissingTagValue" option. The tag
1704           value may be modified via changes to the default input variable
1705           ($_) in a Perl expression placed inside the braces and after a
1706           semicolon following the tag name (see the last example above).  A
1707           '@' may be added after the tag name (before the semicolon) to make
1708           the expression act on individual list items instead of the
1709           concatenated string for list-type tags. Braces within the
1710           expression must be balanced. Multiple options hash references may
1711           be passed to set different options for different tags. Options
1712           apply to subsequent tags in the argument list.
1713
1714           By default, this routine will commute information between same-
1715           named tags in different groups, allowing information to be
1716           translated between images with different formats.  This behaviour
1717           may be modified by specifying a group name for extracted tags (even
1718           if '*' is used as a group name), in which case the information is
1719           written to the original group, unless redirected to a different
1720           group.  When '*' is used for a group name, by default the family 1
1721           group of the original tag is preserved, but a different family may
1722           be specified with a leading family number.  (For example,
1723           specifying '*:*' copies all information while preserving the
1724           original family 1 groups, while '0*:*' preserves the family 0
1725           group.)
1726
1727       SetNewValuesFromFile Options:
1728           The options are the same was for "SetNewValue", and are passed
1729           directly to "SetNewValue" internally, with a few exceptions:
1730
1731           - The Replace option defaults to 1 instead of 0 as with
1732           "SetNewValue", however the tag name argument may be prefixed with
1733           '+' to set the Replace option to 0 for this argument only.
1734
1735           - The AddValue or DelValue option is set for individual tags if
1736           '+>' or '->' (or '+<' or '-<') are used.
1737
1738           - The Group option is set for tags where a group name is given.
1739
1740           - The Protected flag is set to 1 for individually specified tags.
1741
1742           - The Type option also applies to extracted tags.
1743
1744       Return Values:
1745           A hash of information that was set successfully.  May include
1746           Warning or Error entries if there were problems reading the input
1747           file.
1748
1749       Notes:
1750           The PrintConv option applies to this routine, but it normally
1751           should be left on to provide more reliable transfer of information
1752           between groups.
1753
1754           If a preview image exists, it is not copied.  The preview image
1755           must be transferred separately if desired, in a separate call to
1756           "WriteInfo"
1757
1758           When simply copying all information between files of the same type,
1759           it is usually desirable to preserve the original groups by
1760           specifying '*:*' for the tags to set.
1761
1762           The "Duplicates" option is always in effect for tags extracted from
1763           the source file using this routine.
1764
1765           The "Struct" option is enabled by default for tags extracted by
1766           this routine.  This allows the hierarchy of complex structures to
1767           be preserved when copying, but the Struct option may be set to 0 to
1768           override this behaviour and copy as flattened tags instead.
1769
1770   CountNewValues
1771       Return the total number of new values set.
1772
1773           $numSet = $exifTool->CountNewValues();
1774           ($numSet, $numPseudo) = $exifTool->CountNewValues();
1775
1776       Inputs:
1777           0) ExifTool object reference
1778
1779       Return Values:
1780           In scalar context, returns the total number of tags with new values
1781           set.  In list context, also returns the number of "pseudo" tag
1782           values which have been set.  "Pseudo" tags are tags like FileName
1783           and FileModifyDate which are not contained within the file and can
1784           be changed without rewriting the file.
1785
1786   SaveNewValues
1787       Save state of new values to be later restored by "RestoreNewValues".
1788
1789           $exifTool->SaveNewValues();         # save state of new values
1790           $exifTool->SetNewValue(ISO => 100); # set new value for ISO
1791           $exifTool->WriteInfo($src, $dst1);  # write ISO + previous new values
1792           $exifTool->RestoreNewValues();      # restore previous new values
1793           $exifTool->WriteInfo($src, $dst2);  # write previous new values only
1794
1795       Inputs:
1796           0) ExifTool object reference
1797
1798       Return Value:
1799           Count of the number of times this routine has been called (N) since
1800           the last time the new values were reset.
1801
1802   RestoreNewValues
1803       Restore new values to the settings that existed when "SaveNewValues"
1804       was last called.  May be called repeatedly after a single call to
1805       "SaveNewValues".  See "SaveNewValues" above for an example.
1806
1807       Inputs:
1808           0) ExifTool object reference
1809
1810       Return Value:
1811           None.
1812
1813   SetAlternateFile
1814       Specify alternate file from which to read metadata.  Tags from the
1815       alternate file are available after "ExtractInfo" is called or during a
1816       call to "SetNewValuesFromFile" by using a family 8 group name (eg.
1817       'File1' in the example below).
1818
1819           $exifTool->SetAlternateFile(File1 => 'images/test1.jpg');
1820
1821       Inputs:
1822           0) ExifTool object reference
1823
1824           1) Family 8 group name, case insensitive (eg. 'File1', 'File2'...)
1825
1826           2) Name of alternate input file, or undef to reset
1827
1828       Return Values:
1829           1 on success, or 0 if the group name is invalid.
1830
1831   SetFileModifyDate
1832       Write the filesystem modification or creation time from the new value
1833       of the FileModifyDate or FileCreateDate tag.
1834
1835           $exifTool->SetNewValue(FileModifyDate => '2000:01:02 03:04:05-05:00',
1836                                  Protected => 1);
1837           $result = $exifTool->SetFileModifyDate($file);
1838
1839       Inputs:
1840           0) ExifTool object reference
1841
1842           1) File name
1843
1844           2) [optional] Base time if applying shift (days before $^T)
1845
1846           3) [optional] Tag to write: 'FileModifyDate' (default), or
1847           'FileCreateDate'
1848
1849       Return Value:
1850           1 if the time was changed, 0 if nothing was done, or -1 if there
1851           was an error setting the time.
1852
1853       Notes:
1854           Equivalent to, but more efficient than calling "WriteInfo" when
1855           only the FileModifyDate or FileCreateDate tag has been set.  If a
1856           timezone is not specified, local time is assumed.  When shifting,
1857           the time of the original file is used unless the optional base time
1858           is specified.
1859
1860           The ability to write FileCreateDate is currently restricted to
1861           Windows systems only.
1862
1863   SetFileName
1864       Set the file name and directory, or create a hard link.  If not
1865       specified, the new file name is derived from the new values of the
1866       FileName and Directory tags, or from the HardLink or SymLink tag if
1867       creating a link.  If the FileName tag contains a '/', then the file is
1868       renamed into a new directory.  If FileName ends with '/', then it is
1869       taken as a directory name and the file is moved into the new directory.
1870       The new value for the Directory tag takes precedence over any directory
1871       specified in FileName.
1872
1873           $result = $exifTool->SetFileName($file);
1874           $result = $exifTool->SetFileName($file, $newName);
1875
1876       Inputs:
1877           0) ExifTool object reference
1878
1879           1) Current file name
1880
1881           2) [optional] New file name
1882
1883           3) [optional] 'HardLink' or 'SymLink' to create a hard or symbolic
1884           link instead of renaming the file, or 'Test' to test renaming
1885           feature by printing the old and new names instead of changing
1886           anything.
1887
1888       Return Value:
1889           1 on success, 0 if nothing was done, or -1 if there was an error
1890           renaming the file or creating the link.
1891
1892       Notes:
1893           Will not overwrite existing files. New directories are created as
1894           necessary.  If the file is successfully renamed, the new file name
1895           may be accessed via $$exifTool{NewName}.
1896
1897   SetNewGroups
1898       Set the order of the preferred groups when adding new information.  In
1899       subsequent calls to "SetNewValue", new information will be created in
1900       the first valid group of this list.  This has an impact only if the
1901       group is not specified when calling "SetNewValue" and if the tag name
1902       exists in more than one group.  The default order is EXIF, IPTC, XMP,
1903       MakerNotes, QuickTime, Photoshop, ICC_Profile, CanonVRD, Adobe.  Any
1904       family 0 group name may be used.  Case is not significant.
1905
1906           $exifTool->SetNewGroups('XMP','EXIF','IPTC');
1907
1908       Inputs:
1909           0) ExifTool object reference
1910
1911           1-N) Groups in order of priority.  If no groups are specified, the
1912           priorities are reset to the defaults.
1913
1914       Return Value:
1915           None.
1916
1917   GetNewGroups
1918       Get current group priority list.
1919
1920           @groups = $exifTool->GetNewGroups();
1921
1922       Inputs:
1923           0) ExifTool object reference
1924
1925       Return Values:
1926           List of group names in order of write priority.  Highest priority
1927           first.
1928
1929   GetTagID
1930       Get the ID for the specified tag.  The ID is the IFD tag number in EXIF
1931       information, the property name in XMP information, or the data offset
1932       in a binary data block.  For some tags, such as Composite tags where
1933       there is no ID, an empty string is returned.  In list context, also
1934       returns a language code for the tag if available and different from the
1935       default language (eg.  with alternate language entries for XMP "lang-
1936       alt" tags).
1937
1938           $id = $exifTool->GetTagID($tag);
1939           ($id, $lang) = $exifTool->GetTagID($tag);
1940
1941       Inputs:
1942           0) ExifTool object reference
1943
1944           1) Tag key
1945
1946       Return Values:
1947           In scalar context, returns the tag ID or '' if there is no ID for
1948           this tag.  In list context, returns the tag ID (or '') and the
1949           language code (or undef).
1950
1951   GetDescription
1952       Get description for specified tag.  This function will always return a
1953       defined value.  In the case where the description doesn't exist, one is
1954       generated from the tag name.
1955
1956       Inputs:
1957           0) ExifTool object reference
1958
1959           1) Tag key
1960
1961       Return Values:
1962           A description for the specified tag.
1963
1964   GetGroup
1965       Get group name(s) for a specified tag.
1966
1967           # return family 0 group name (eg. 'EXIF');
1968           $group = $exifTool->GetGroup($tag, 0);
1969
1970           # return all groups (eg. qw{EXIF IFD0 Author Main})
1971           @groups = $exifTool->GetGroup($tag);
1972
1973           # return groups as a string (eg. 'Main:IFD0:Author')
1974           $group = $exifTool->GetGroup($tag, ':3:1:2');
1975
1976           # return groups as a simplified string (eg. 'IFD0:Author')
1977           $group = $exifTool->GetGroup($tag, '3:1:2');
1978
1979       Inputs:
1980           0) ExifTool object reference
1981
1982           1) Tag key
1983
1984           2) [optional] Group family number, or string of numbers separated
1985           by colons
1986
1987       Return Values:
1988           Group name (or '' if tag has no group).  If no group family is
1989           specified, "GetGroup" returns the name of the group in family 0
1990           when called in scalar context, or the names of groups for all
1991           families in list context.  Returns a string of group names
1992           separated by colons if the input group family contains a colon.
1993           The string is simplified to remove a leading 'Main:' and adjacent
1994           identical group names unless the family string begins with a colon.
1995
1996       Notes:
1997           The group family numbers are currently available:
1998
1999               0) Information Type         (eg. EXIF, XMP, IPTC)
2000               1) Specific Location        (eg. IFD0, XMP-dc)
2001               2) Category                 (eg. Author, Time)
2002               3) Document Number          (eg. Main, Doc1, Doc3-2)
2003               4) Instance Number          (eg. Copy1, Copy2, Copy3...)
2004               5) Metadata Path            (eg. JPEG-APP1-IFD0-ExifIFD)
2005               6) EXIF/TIFF Format         (eg. int8u, int32u, undef, string)
2006               7) Tag ID                   (eg. ID-271, ID-rights, ID-a9aut)
2007               8) Alternate File Number    (eg. File1, File2, File3...)
2008
2009           Families 0 and 1 are based on the file structure, and are similar
2010           except that family 1 is more specific and sub-divides some groups
2011           to give more detail about the specific location where the
2012           information was found.  For example, the EXIF group is split up
2013           based on the specific IFD (Image File Directory), the MakerNotes
2014           group is divided into groups for each manufacturer, and the XMP
2015           group is separated based on the XMP namespace prefix.  Note that
2016           only common XMP namespaces are listed in the GetAllGroups
2017           documentation, but additional namespaces may be present in some XMP
2018           data.  Also note that the 'XMP-xmp...'  group names may appear in
2019           the older form 'XMP-xap...' since these names evolved as the XMP
2020           standard was developed.  The ICC_Profile group is broken down to
2021           give information about the specific ICC_Profile tag from which
2022           multiple values were extracted.  As well, information extracted
2023           from the ICC_Profile header is separated into the ICC-header group.
2024
2025           Family 2 classifies information based on the logical category to
2026           which the information refers.
2027
2028           Family 3 gives the document number for tags extracted from embedded
2029           documents, or 'Main' for tags from the main document.  (See the
2030           "ExtractEmbedded" option for extracting tags from embedded
2031           documents.)  Nested sub-documents (if they exist) are indicated by
2032           numbers separated with dashes in the group name, to an arbitrary
2033           depth. (eg. 'Doc2-3-1' is the 1st sub-sub-document of the 3rd sub-
2034           document of the 2nd embedded document of the main file.)  Document
2035           numbers are also used to differentiate samples for timed metadata
2036           in videos.
2037
2038           Family 4 provides a method for differentiating tags when multiple
2039           tags exist with the same name in the same location.  The primary
2040           instance of a tag (the tag extracted when the Duplicates option is
2041           disabled and no group is specified) has no family 4 group name, but
2042           additional instances have family 4 group names of 'Copy1', 'Copy2',
2043           'Copy3', etc.  For convenience, the primary tag may also be
2044           accessed using a group name of 'Copy0'.
2045
2046           Family 5 is experimental, and gives the complete path for the
2047           metadata in the file.  Generated only if the "SavePath" option is
2048           used when extracting.
2049
2050           Family 6 is currently used only for EXIF/TIFF metadata, and gives
2051           the format type of the extracted value.  Generated only if the
2052           "SaveFormat" option is used when extracting.
2053
2054           Family 7 is used for tag ID's.  The group names are the actual tag
2055           ID's, with a leading "ID-" string.  Non-numerical ID's have
2056           characters other than [-_A-Za-z0-9] converted to hex.  Numerical
2057           tag ID's are returned in hex if the "HexTagIDs" option is set,
2058           otherwise decimal is used.  When specifying a family 7 group name,
2059           numerical ID's may be in hex or decimal, and non-numerical ID's may
2060           or may not have characters other than [-_A-Za-z0-9] converted to
2061           hex.  Note that unlike other group names, the tag ID's of family 7
2062           group names are case sensitive (but the leading "ID-" is not).
2063
2064           Family 8 specifies the alternate file set from a call to
2065           "SetAlternateFile".
2066
2067           See "GetAllGroups [static]" for complete lists of group names.
2068
2069   GetGroups
2070       Get list of group names that exist in the specified information.
2071
2072           @groups = $exifTool->GetGroups($info, 2);
2073           @groups = $exifTool->GetGroups('3:1');
2074
2075       Inputs:
2076           0) ExifTool object reference
2077
2078           1) [optional] Info hash ref (default is all extracted info)
2079
2080           2) [optional] Group family number, or string of numbers (default 0)
2081
2082       Return Values:
2083           List of group names in alphabetical order. If information hash is
2084           not specified, the group names are returned for all extracted
2085           information. See "GetGroup" for an description of family numbers
2086           and family number strings.
2087
2088   BuildCompositeTags
2089       Builds composite tags from required tags.  The composite tags are
2090       convenience tags which are derived from the values of other tags.  This
2091       routine is called automatically by "ImageInfo" and "ExtractInfo" if the
2092       Composite option is set.
2093
2094       Inputs:
2095           0) ExifTool object reference
2096
2097       Return Values:
2098           (none)
2099
2100       Notes:
2101           Tag values are calculated in alphabetical order unless a tag
2102           Require's or Desire's another composite tag, in which case the
2103           calculation is deferred until after the other tag is calculated.
2104
2105           Composite tags may need to read data from the image for their value
2106           to be determined, and for these "BuildCompositeTags" must be called
2107           while the image is available.  This is only a problem if
2108           "ImageInfo" is called with a filename (as opposed to a file
2109           reference or scalar reference) since in this case the file is
2110           closed before "ImageInfo" returns.  Here the Composite option may
2111           be used so that "BuildCompositeTags" is called from within
2112           "ImageInfo", before the file is closed.
2113
2114   AvailableOptions [static]
2115       Get a list of available API options. (See "Options" for option
2116       details.)
2117
2118       Inputs:
2119           (none)
2120
2121       Return Values:
2122           Reference to list of available options.  Each entry in the list is
2123           a list reference with 3 items: 0=Option name, 1=Default value,
2124           2=Description.
2125
2126               my $opts = Image::ExifTool::<b>AvailableOptions</b>();
2127               foreach (@$opts) {
2128                   my ($optionName, $defaultValue, $description) = @$_;
2129                   ...
2130               }
2131
2132   GetTagName [static]
2133       Get name of tag from tag key.  This is a convenience function that
2134       strips the embedded instance number, if it exists, from the tag key.
2135
2136       Note: "static" in the heading above indicates that the function does
2137       not require an ExifTool object reference as the first argument.  All
2138       functions documented below are also static.
2139
2140           $tagName = Image::ExifTool::GetTagName($tag);
2141
2142       Inputs:
2143           0) Tag key
2144
2145       Return Value:
2146           Tag name.  This is the same as the tag key but has the instance
2147           number removed.
2148
2149   GetShortcuts [static]
2150       Get a list of shortcut tags.
2151
2152       Inputs:
2153           (none)
2154
2155       Return Values:
2156           List of shortcut tags (as defined in Image::ExifTool::Shortcuts).
2157
2158   GetAllTags [static]
2159       Get list of all available tag names.
2160
2161           @tagList = Image::ExifTool::GetAllTags($group);
2162
2163       Inputs:
2164           0) [optional] Group name, or string of group names separated by
2165           colons
2166
2167       Return Values:
2168           A list of all available tags in alphabetical order, or all tags in
2169           a specified group or intersection of groups.  The group name is
2170           case insensitive, and any group in families 0-2 may be used except
2171           for EXIF family 1 groups (ie. the specific IFD).
2172
2173   GetWritableTags [static]
2174       Get list of all writable tag names.
2175
2176           @tagList = Image::ExifTool::GetWritableTags($group);
2177
2178       Inputs:
2179           0) [optional] Group name, or string of group names separated by
2180           colons
2181
2182       Return Values:
2183           A list of all writable tags in alphabetical order.  These are the
2184           tags for which values may be set through "SetNewValue".  If a group
2185           name is given, returns only writable tags in specified group(s).
2186           The group name is case insensitive, and any group in families 0-2
2187           may be used except for EXIF family 1 groups (ie. the specific IFD).
2188
2189   GetAllGroups [static]
2190       Get list of all group names in specified family.
2191
2192           @groupList = Image::ExifTool::GetAllGroups($family);
2193
2194       Inputs:
2195           0) Group family number (0-7)
2196
2197       Return Values:
2198           A list of all groups in the specified family in alphabetical order.
2199
2200       Here is a complete list of groups for each of these families:
2201
2202       Family 0 (Information Type):
2203           AFCP, AIFF, APE, APP0, APP1, APP11, APP12, APP13, APP14, APP15,
2204           APP2, APP3, APP4, APP5, APP6, APP8, ASF, Audible, CanonVRD,
2205           Composite, DICOM, DNG, DV, DjVu, Ducky, EXE, EXIF, ExifTool, FITS,
2206           FLAC, FLIR, File, Flash, FlashPix, Font, FotoStation, GIF, GIMP,
2207           GeoTiff, GoPro, H264, HTML, ICC_Profile, ID3, IPTC, ISO, ITC, JFIF,
2208           JPEG, JSON, JUMBF, Jpeg2000, LNK, Leaf, Lytro, M2TS, MIE, MIFF,
2209           MISB, MNG, MOI, MPC, MPEG, MPF, MXF, MakerNotes, Matroska, Meta,
2210           Ogg, OpenEXR, Opus, PDF, PICT, PLIST, PNG, PSP, Palm, Parrot,
2211           PanasonicRaw, PhotoCD, PhotoMechanic, Photoshop, PostScript,
2212           PrintIM, QuickTime, RAF, RIFF, RSRC, RTF, Radiance, Rawzor, Real,
2213           Red, SVG, SigmaRaw, Stim, Theora, Torrent, Trailer, UserParam,
2214           VCard, Vorbis, WTV, XML, XMP, ZIP
2215
2216       Family 1 (Specific Location):
2217           AC3, AFCP, AIFF, APE, ASF, AVI1, Adobe, AdobeCM, AdobeDNG, Apple,
2218           Audible, CBOR, CIFF, CameraIFD, Canon, CanonCustom, CanonDR4,
2219           CanonRaw, CanonVRD, Casio, Chapter#, Composite, DICOM, DJI, DNG,
2220           DV, DjVu, DjVu-Meta, Ducky, EPPIM, EXE, EXIF, ExifIFD, ExifTool,
2221           FITS, FLAC, FLIR, File, Flash, FlashPix, Font, FotoStation,
2222           FujiFilm, FujiIFD, GE, GIF, GIMP, GPS, GSpherical, Garmin, GeoTiff,
2223           GlobParamIFD, GoPro, GraphConv, H264, HP, HTC, HTML, HTML-dc, HTML-
2224           ncc, HTML-office, HTML-prod, HTML-vw96, HTTP-equiv, ICC-chrm, ICC-
2225           clrt, ICC-header, ICC-meas, ICC-meta, ICC-view, ICC_Profile,
2226           ICC_Profile#, ID3, ID3v1, ID3v1_Enh, ID3v2_2, ID3v2_3, ID3v2_4,
2227           IFD0, IFD1, IPTC, IPTC#, ISO, ITC, InfiRay, Insta360, InteropIFD,
2228           ItemList, JFIF, JFXX, JPEG, JPEG-HDR, JPS, JSON, JUMBF, JVC,
2229           Jpeg2000, KDC_IFD, Keys, Kodak, KodakBordersIFD, KodakEffectsIFD,
2230           KodakIFD, KyoceraRaw, LNK, Leaf, LeafSubIFD, Leica, Lyrics3, Lytro,
2231           M-RAW, M2TS, MAC, MIE-Audio, MIE-Camera, MIE-Canon, MIE-Doc, MIE-
2232           Extender, MIE-Flash, MIE-GPS, MIE-Geo, MIE-Image, MIE-Lens, MIE-
2233           Main, MIE-MakerNotes, MIE-Meta, MIE-Orient, MIE-Preview, MIE-
2234           Thumbnail, MIE-UTM, MIE-Unknown, MIE-Video, MIFF, MISB, MNG, MOBI,
2235           MOI, MPC, MPEG, MPF0, MPImage, MS-DOC, MXF, MacOS, MakerNotes,
2236           MakerUnknown, Matroska, MediaJukebox, Meta, MetaIFD, Microsoft,
2237           Minolta, MinoltaRaw, Motorola, NITF, Nikon, NikonCapture,
2238           NikonCustom, NikonScan, NikonSettings, NineEdits, Nintendo, Ocad,
2239           Ogg, Olympus, OpenEXR, Opus, PDF, PICT, PNG, PNG-cICP, PNG-pHYs,
2240           PSP, Palm, Panasonic, PanasonicRaw, Parrot, Pentax, PhaseOne,
2241           PhotoCD, PhotoMechanic, Photoshop, PictureInfo, PostScript,
2242           PreviewIFD, PrintIM, ProfileIFD, Qualcomm, QuickTime, RAF, RAF2,
2243           RIFF, RMETA, RSRC, RTF, Radiance, Rawzor, Real, Real-CONT, Real-
2244           MDPR, Real-PROP, Real-RA3, Real-RA4, Real-RA5, Real-RJMD, Reconyx,
2245           Red, Ricoh, SPIFF, SR2, SR2DataIFD, SR2SubIFD, SRF#, SVG, Samsung,
2246           Sanyo, Scalado, Sigma, SigmaRaw, Sony, SonyIDC, Stim, SubIFD,
2247           System, Theora, Torrent, Track#, UserData, VCalendar, VCard, VNote,
2248           Version0, Vorbis, WTV, XML, XMP, XMP-DICOM, XMP-Device, XMP-GAudio,
2249           XMP-GCamera, XMP-GCreations, XMP-GDepth, XMP-GFocus, XMP-GImage,
2250           XMP-GPano, XMP-GSpherical, XMP-LImage, XMP-MP, XMP-MP1, XMP-
2251           PixelLive, XMP-aas, XMP-acdsee, XMP-album, XMP-apple-fi, XMP-ast,
2252           XMP-aux, XMP-cc, XMP-cell, XMP-crd, XMP-creatorAtom, XMP-crs, XMP-
2253           dc, XMP-dex, XMP-digiKam, XMP-drone-dji, XMP-dwc, XMP-et, XMP-exif,
2254           XMP-exifEX, XMP-expressionmedia, XMP-extensis, XMP-fpv, XMP-getty,
2255           XMP-hdr, XMP-hdrgm, XMP-ics, XMP-iptcCore, XMP-iptcExt, XMP-lr,
2256           XMP-mediapro, XMP-microsoft, XMP-mwg-coll, XMP-mwg-kw, XMP-mwg-rs,
2257           XMP-nine, XMP-panorama, XMP-pdf, XMP-pdfx, XMP-photomech, XMP-
2258           photoshop, XMP-plus, XMP-pmi, XMP-prism, XMP-prl, XMP-prm, XMP-pur,
2259           XMP-rdf, XMP-sdc, XMP-swf, XMP-tiff, XMP-x, XMP-xmp, XMP-xmpBJ,
2260           XMP-xmpDM, XMP-xmpMM, XMP-xmpNote, XMP-xmpPLUS, XMP-xmpRights, XMP-
2261           xmpTPg, ZIP, iTunes
2262
2263       Family 2 (Category):
2264           Audio, Author, Camera, Device, Document, ExifTool, Image, Location,
2265           Other, Preview, Printing, Time, Unknown, Video
2266
2267       Family 3 (Document Number):
2268           Doc#, Main
2269
2270       Family 4 (Instance Number):
2271           Copy#
2272
2273       Family 5 (Metadata Path):
2274           eg. JPEG-APP1-IFD0-ExifIFD
2275
2276       Family 6 (EXIF/TIFF Format):
2277           int8u, string, int16u, int32u, rational64u, int8s, undef, int16s,
2278           int32s, rational64s, float, double, ifd, unicode, complex, int64u,
2279           int64s, ifd64
2280
2281       Family 7 (Tag ID):
2282           ID-xxx (Where xxx is the tag ID.  Numerical ID's are returned in
2283           hex with a leading "0x" if the HexTagIDs option is set, or decimal
2284           otherwise.  Characters in non-numerical ID's which are not valid in
2285           a group name are returned as 2 hex digits.)
2286
2287       Family 8 (Alternate File):
2288           File#
2289
2290       Note:  This function may also be called as an ExifTool member function
2291       to allow the HexTagIDs option to be set when retrieving family 7 group
2292       names.
2293
2294   GetDeleteGroups [static]
2295       Get list of all deletable group names.
2296
2297           @delGroups = Image::ExifTool::GetDeleteGroups();
2298
2299       Inputs:
2300           None.
2301
2302       Return Values:
2303           A list of deletable group names in alphabetical order.  The current
2304           list of deletable group names is:
2305
2306           Adobe, AFCP, APP0, APP1, APP10, APP11, APP12, APP13, APP14, APP15,
2307           APP2, APP3, APP4, APP5, APP6, APP7, APP8, APP9, Audio, Author,
2308           Camera, CanonVRD, CIFF, Document, Ducky, EXIF, ExifIFD, ExifTool,
2309           File, FlashPix, FotoStation, GlobParamIFD, GPS, ICC_Profile, IFD0,
2310           IFD1, Image, Insta360, InteropIFD, IPTC, ItemList, JFIF, Jpeg2000,
2311           Keys, Location, MakerNotes, Meta, MetaIFD, Microsoft, MIE, MPF,
2312           NikonCapture, Other, PDF, PDF-update, PhotoMechanic, Photoshop,
2313           PNG, PNG-pHYs, Preview, PrintIM, Printing, QuickTime, RMETA, RSRC,
2314           SubIFD, Time, Trailer, UserData, Video, XML, XML-*, XMP, XMP-*
2315
2316           To schedule a group for deletion, call "SetNewValue" with a tag
2317           name like 'EXIF:*' and an undefined tag value.
2318
2319           Deleting a family 0 or 1 group will delete the entire corresponding
2320           block of metadata, but deleting a family 2 group (eg. Audio,
2321           Author, Camera, etc.)  deletes the individual tags belonging to
2322           that category.
2323
2324           The 'Trailer' group allows all trailers in JPEG and TIFF-format
2325           images to be deleted at once, including unknown trailers.  Note
2326           that the JPEG "APP" groups are special, and are used only to delete
2327           application segments which are not associated with another
2328           deletable group. For example, deleting 'APP14:*' will delete other
2329           APP14 segments, but not the APP14 "Adobe" segment.
2330
2331   GetFileType [static]
2332       Get type of file given file name.
2333
2334           my $type = Image::ExifTool::GetFileType($filename);
2335           my $desc = Image::ExifTool::GetFileType($filename, 1);
2336
2337       Inputs:
2338           0) [optional] File name (or just an extension)
2339
2340           1) [optional] Flag to return a description instead of a type.
2341           Default is undef.  Set to 0 to also return types of recognized but
2342           unsupported files (otherwise the return value for unsupported files
2343           is undef), or 1 to return descriptions.
2344
2345       Return Value:
2346           A string, based on the file extension, which indicates the basic
2347           format of the file.  Note that some files may be based on other
2348           formats (like many RAW image formats are based on TIFF).  In list
2349           context, may return more than one file type if the file may be
2350           based on different formats.  Returns undef if files with this
2351           extension are not yet supported by ExifTool.  Returns a list of
2352           extensions for all supported file types if no input extension is
2353           specified (or all recognized file types if the description flag is
2354           set to 0). Returns a more detailed description of the specific file
2355           format when the description flag is set.
2356
2357   CanWrite [static]
2358       Can the specified file be written?
2359
2360           my $writable = Image::ExifTool::CanWrite($filename);
2361
2362       Inputs:
2363           0) File name or extension
2364
2365       Return Value:
2366           True if ExifTool supports writing files of this type (based on the
2367           file extension).
2368
2369   CanCreate [static]
2370       Can the specified file be created?
2371
2372           my $creatable = Image::ExifTool::CanCreate($filename);
2373
2374       Inputs:
2375           0) File name or extension
2376
2377       Return Value:
2378           True if ExifTool can create files with this extension from scratch.
2379           Currently, this can only be done with XMP, MIE, ICC, VRD, DR4, EXV
2380           and EXIF files.
2381
2382   AddUserDefinedTags [static]
2383       Add user-defined tags to an existing tag table at run time.  This
2384       differs from the usual technique of creating user-defined tags via the
2385       %Image::ExifTool::UserDefined hash (see the ExifTool_config file in the
2386       Image::ExifTool distribution) because it allows tags to be added after
2387       a tag table has been initialized.
2388
2389           use Image::ExifTool ':Public';
2390           my %tags = (
2391               TestTagID1 => { Name => 'TestTagName1' },
2392               TestTagID2 => { Name => 'TestTagName2' },
2393           );
2394           my $num = AddUserDefinedTags('Image::ExifTool::PDF::Info', %tags);
2395
2396       Inputs:
2397           0) Destination tag table name
2398
2399           1-N) Pairs of tag ID / tag information hash references for the new
2400           tags
2401
2402       Return Value:
2403           The number of tags added.
2404
2405       Notes
2406           Pre-existing tags with the same ID will be replaced in the
2407           destination table. See lib/Image/ExifTool/README in the full
2408           distribution for full details on the elements of the tag
2409           information hash.
2410

CHARACTER ENCODINGS

2412       Certain meta information formats allow coded character sets other than
2413       plain ASCII.  When reading, most known encodings are converted to the
2414       external character set according to the "Charset" option, or to UTF-8
2415       by default.  When writing, the inverse conversions are performed.
2416       Alternatively, special characters may be converted to/from HTML
2417       character entities with the "Escape" HTML option.
2418
2419       A distinction is made between the external character set visible via
2420       the ExifTool API, and the internal character used to store text in the
2421       metadata of a file.  These character sets may be specified separately
2422       as follows:
2423
2424       External Character Sets:
2425           The encoding for tag values passed to/from ExifTool API functions
2426           is set via the "Charset" option, which is 'UTF8' by default.
2427
2428           The encoding of file names is specified via the "CharsetFileName"
2429           option.  By default, "CharsetFileName" is not defined, and file
2430           names passed to ExifTool are used directly in calls to the system
2431           i/o routines (which expect UTF-8 strings on Mac/Linux, but default
2432           to the system code page on Windows).  In this mode on Windows a
2433           warning is issued if a file name contains special characters, but
2434           this warning may be avoided by setting "CharsetFileName" to an
2435           empty string.  Setting "CharsetFileName" to any other value causes
2436           file names to be converted from the specified encoding to one
2437           appropriate for the system.  In Windows this also has the effect of
2438           activating Unicode filename support via the special Windows wide-
2439           character i/o routines if Win32API::File is available.
2440
2441       Internal Character Sets:
2442           The encodings used to store strings in the various metadata
2443           formats.  These encodings may be changed for certain types of
2444           metadata via the "CharsetEXIF", "CharsetID3", "CharsetIPTC",
2445           "CharsetPhotoshop", "CharsetQuickTime" and "CharsetRIFF" options.
2446
2447       Values are returned as byte strings of encoded characters.  Perl wide
2448       characters are not used.  By default, most returned strings are encoded
2449       in UTF-8.  For these, Encode::decode_utf8() may be used to convert to a
2450       sequence of logical Perl characters.  Note that some settings of the
2451       PERL_UNICODE environment variable may be incompatible with ExifTool's
2452       character handling.
2453
2454       More specific details are given below about how character coding is
2455       handled for EXIF, IPTC, XMP, PNG, ID3, PDF, Photoshop, QuickTime, AIFF,
2456       MIE and Vorbis information:
2457
2458   EXIF
2459       Most textual information in EXIF is stored in ASCII format (called
2460       "string" in the ExifTool tag name documentation). By default ExifTool
2461       does not convert these strings.  However, it is not uncommon for
2462       applications to write UTF-8 or other encodings where ASCII is expected.
2463       To deal with these, ExifTool allows the internal EXIF string encoding
2464       to be specified with "CharsetEXIF", which causes EXIF string values to
2465       be converted from the specified character set when reading, and stored
2466       with this character set when writing.  (The MWG recommends using UTF-8
2467       encoding for EXIF strings, and in keeping with this the MWG module sets
2468       the default internal EXIF string encoding to UTF-8, but note that this
2469       will have no effect unless the external encoding is also set to
2470       something other than the default of UTF-8.)
2471
2472       A few EXIF tags (UserComment, GPSProcessingMethod and
2473       GPSAreaInformation) support a designated internal text encoding, with
2474       values stored as ASCII, Unicode (UCS-2) or JIS.  When reading these
2475       tags, ExifTool converts Unicode and JIS to the external character set
2476       specified by the "Charset" option, or to UTF-8 by default.  ASCII text
2477       is not converted. When writing, text is stored as ASCII unless the
2478       string contains special characters, in which case it is converted from
2479       the external character set (UTF-8 by default), and stored as Unicode.
2480       ExifTool writes Unicode in native EXIF byte ordering by default, but
2481       the byte order may be specified by setting the ExifUnicodeByteOrder tag
2482       (see the Extra Tags documentation).
2483
2484       The EXIF "XP" tags (XPTitle, XPComment, etc) are always stored as
2485       little-endian Unicode (UCS-2), and are read and written using the
2486       specified character set.
2487
2488   IPTC
2489       The value of the IPTC:CodedCharacterSet tag determines how the internal
2490       IPTC string values are interpreted.  If CodedCharacterSet exists and
2491       has a value of 'UTF8' (or 'ESC % G') then string values are assumed to
2492       be stored as UTF-8, otherwise Windows Latin1 (cp1252, 'Latin') coding
2493       is assumed by default, but this can be changed with the "CharsetIPTC"
2494       option.  When reading, these strings are converted to the character set
2495       specified by the "Charset" option.  When writing, the inverse
2496       conversions are performed.  No conversion is done if the internal
2497       (IPTC) and external (ExifTool) character sets are the same.  Note that
2498       ISO 2022 character set shifting is not supported.  Instead, a warning
2499       is issued and the string is not converted if an ISO 2022 shift code is
2500       encountered.  See <http://www.iptc.org/IIM/> for the official IPTC
2501       specification.
2502
2503       ExifTool may be used to convert IPTC values to a different internal
2504       encoding.  To do this, all IPTC tags must be rewritten along with the
2505       desired value of CodedCharacterSet.  For example, the following command
2506       changes the internal IPTC encoding to UTF-8 (from Windows Latin1 unless
2507       CodedCharacterSet was already 'UTF8'):
2508
2509         exiftool -tagsfromfile @ -iptc:all -codedcharacterset=utf8 a.jpg
2510
2511       or from Windows Latin2 (cp1250) to UTF-8:
2512
2513         exiftool -tagsfromfile @ -iptc:all -codedcharacterset=utf8 \
2514         -charset iptc=latin2 a.jpg
2515
2516       and this command changes it back from UTF-8 to Windows Latin1 (cp1252):
2517
2518         exiftool -tagsfromfile @ -iptc:all -codedcharacterset= a.jpg
2519
2520       or to Windows Latin2:
2521
2522         exiftool -tagsfromfile @ -iptc:all -codedcharacterset= \
2523         -charset iptc=latin2 a.jpg
2524
2525       Unless CodedCharacterSet is 'UTF8', applications have no reliable way
2526       to determine the IPTC character encoding.  For this reason, it is
2527       recommended that CodedCharacterSet be set to 'UTF8' when creating new
2528       IPTC.
2529
2530       (Note: Here, "IPTC" Refers to the older IPTC IIM format.  The more
2531       recent IPTC Core and Extension specifications actually use the XMP
2532       format.)
2533
2534   XMP
2535       ExifTool reads XMP encoded as UTF-8, UTF-16 or UTF-32, and converts
2536       them all to UTF-8 internally.  Also, all XML character entity
2537       references and numeric character references are converted.  When
2538       writing, ExifTool always encodes XMP as UTF-8, converting the following
2539       5 characters to XML character references: & < > ' ".  By default no
2540       further conversion is performed, however if the "Charset" option is
2541       other than 'UTF8' then text is converted to/from the specified
2542       character set when reading/writing.
2543
2544   PNG
2545       PNG TextualData tags are stored as tEXt, zTXt and iTXt chunks in PNG
2546       images.  The tEXt and zTXt chunks use ISO 8859-1 encoding, while iTXt
2547       uses UTF-8.  When reading, ExifTool converts all PNG textual data to
2548       the character set specified by the "Charset" option.  When writing,
2549       ExifTool generates a tEXt chunk (or zTXt with the "Compress" option) if
2550       the text doesn't contain special characters or if Latin encoding is
2551       specified; otherwise an iTXt chunk is used and the text is converted
2552       from the specified character set and stored as UTF-8.
2553
2554   JPEG Comment
2555       The encoding for the JPEG Comment (COM segment) is not specified, so
2556       ExifTool reads/writes this text without conversion.
2557
2558   ID3
2559       The ID3v1 specification officially supports only ISO 8859-1 encoding (a
2560       subset of Windows Latin1), although some applications may incorrectly
2561       use other character sets.  By default ExifTool converts ID3v1 text from
2562       Latin to the character set specified by the "Charset" option.  However,
2563       the internal ID3v1 charset may be specified with the "CharsetID3"
2564       option.  The encoding for ID3v2 information is stored in the file, so
2565       ExifTool converts ID3v2 text from this encoding to the character set
2566       specified by the "Charset" option. ExifTool does not currently write
2567       ID3 information.
2568
2569   PDF
2570       PDF text strings are stored in either PDFDocEncoding (similar to
2571       Windows Latin1) or Unicode (UCS-2).  When reading, ExifTool converts to
2572       the character set specified by the "Charset" option.  When writing,
2573       ExifTool encodes input text from the specified character set as Unicode
2574       only if the string contains special characters, otherwise
2575       PDFDocEncoding is used.
2576
2577   Photoshop
2578       Some Photoshop resource names are stored as Pascal strings with unknown
2579       encoding.  By default, ExifTool assumes MacRoman encoding and converts
2580       this to UTF-8, but the internal and external character sets may be
2581       specified with the "CharsetPhotoshop" and "Charset" options
2582       respectively.
2583
2584   QuickTime
2585       QuickTime text strings may be stored in a variety of poorly document
2586       formats. ExifTool does its best to decode these according to the
2587       "Charset" option setting.  For some QuickTime strings, ExifTool assumes
2588       a default encoding of MacRoman, but this may be changed with the
2589       "CharsetQuickTime" option.
2590
2591   AIFF
2592       AIFF strings are assumed to be stored in MacRoman, and are converted
2593       according to the "Charset" option when reading.
2594
2595   RIFF
2596       The internal encoding of RIFF strings (eg. in AVI and WAV files) is
2597       assumed to be Latin unless otherwise specified by the RIFF CSET chunk
2598       or the "CharsetRIFF" option.
2599
2600   MIE
2601       MIE strings are stored as either UTF-8 or ISO 8859-1. When reading,
2602       UTF-8 strings are converted according to the "Charset" option, and ISO
2603       8859-1 strings are never converted.  When writing, input strings are
2604       converted from the specified character set to UTF-8.  The resulting
2605       strings are stored as UTF-8 if they contain multi-byte UTF-8 character
2606       sequences, otherwise they are stored as ISO 8859-1.
2607
2608   Vorbis
2609       Vorbis comments are stored as UTF-8, and are converted to the character
2610       set specified by the "Charset" option.
2611

AUTHOR

2613       Copyright 2003-2023, Phil Harvey
2614
2615       This library is free software; you can redistribute it and/or modify it
2616       under the same terms as Perl itself.
2617

ACKNOWLEDGEMENTS

2619       Many people have helped in the development of ExifTool through their
2620       bug reports, comments and suggestions, and/or additions to the code.
2621       See the ACKNOWLEDGEMENTS in the individual Image::ExifTool modules and
2622       in html/index.html of the Image::ExifTool distribution package for a
2623       list of people who have contributed to this project.
2624

SEE ALSO

2626       exiftool(1), Image::ExifTool::TagNames(3pm),
2627       Image::ExifTool::Shortcuts(3pm), Image::ExifTool::Shift(3pm),
2628       Image::Info(3pm), Image::MetaData::JPEG(3pm)
2629
2630
2631
2632perl v5.38.0                      2023-11-21                Image::ExifTool(3)
Impressum