1Image::ExifTool(3) User Contributed Perl Documentation Image::ExifTool(3)
2
6 Image::ExifTool - Read and write meta information
7
9 use Image::ExifTool qw(:Public);
10 # ---- Simple procedural usage ----
12 # Get hash of meta information tag names/values from an image
14 $info = ImageInfo('a.jpg');
15 # ---- Object-oriented usage ----
17 # Create a new Image::ExifTool object
19 $exifTool = Image::ExifTool->new;
20 # Extract meta information from an image
22 $exifTool->ExtractInfo($file, \%options);
23 # Get list of tags in the order they were found in the file
25 @tagList = $exifTool->GetFoundTags('File');
26 # Get the value of a specified tag
28 $value = $exifTool->GetValue($tag, $type);
29 # Get a tag description
31 $description = $exifTool->GetDescription($tag);
32 # Get the group name associated with this tag
34 $group = $exifTool->GetGroup($tag, $family);
35 # Set a new value for a tag
37 $exifTool->SetNewValue($tag, $newValue);
38 # Write new meta information to a file
40 $success = $exifTool->WriteInfo($srcfile, $dstfile);
41 # ...plus a host of other useful methods...
43
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 Below is a list of file types and meta information formats currently
53 supported by ExifTool (r = read, w = write, c = create):
54 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 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
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 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 BEGIN { $Image::ExifTool::configFile = '/Users/phil/myconfig.cfg' }
133 use Image::ExifTool;
134 The configuration feature may also be disabled by setting "configFile"
136 to an empty string:
137 BEGIN { $Image::ExifTool::configFile = '' }
139 use Image::ExifTool;
140
142 Exports nothing by default, but "ImageInfo" and all static methods may
143 be exported with the ":Public" export list.
144
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 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 The ExifTool methods are not thread safe.
160 new
162 Creates a new ExifTool object.
163 $exifTool = Image::ExifTool->new;
165 One ExifTool object may be used to process many files, so creating
167 multiple ExifTool objects usually is not necessary.
168 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 sub AUTOLOAD
174 {
175 Image::ExifTool::DoAutoLoad($AUTOLOAD, @_);
176 }
177 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 # return meta information for 2 tags only (procedural)
186 $info = ImageInfo($filename, $tag1, $tag2);
187 # return information about an open image file (object-oriented)
189 $info = $exifTool->ImageInfo(\*FILE);
190 # 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 # extract information from an embedded thumbnail image
197 $info = ImageInfo('image.jpg', 'thumbnailimage');
198 $thumbInfo = ImageInfo($$info{ThumbnailImage});
199 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 Below is an explanation of how the "ImageInfo" function arguments
212 are interpreted:
213 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 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 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 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 See Image::ExifTool::TagNames for a complete list of ExifTool
252 tag names.
253 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 [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 SCALAR ref
273 A reference to image data in memory.
274 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 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 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 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 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 foreach (sort keys %$info) {
312 print "$_ => $$info{$_}\n";
313 }
314 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 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 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 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 As well as tags representing information extracted from the image,
361 the following Extra tags generated by ExifTool may be returned:
362 ExifToolVersion - The ExifTool version number.
364 Error - An error message if the image could not be processed.
366 Warning - A warning message if problems were encountered while
368 processing the image.
369 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 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 # exclude the 'OwnerName' tag from returned information
384 $exifTool->Options(Exclude => 'OwnerName');
385 # only get information in EXIF or MakerNotes groups
387 $exifTool->Options(Group0 => ['EXIF', 'MakerNotes']);
388 # ignore information from IFD1
390 $exifTool->Options(Group1 => '-IFD1');
391 # sort by groups in family 2, and extract unknown tags
393 $exifTool->Options(Sort => 'Group2', Unknown => 1);
394 # reset DateFormat option
396 $exifTool->Options(DateFormat => undef);
397 # do not extract duplicate tag names
399 $oldSetting = $exifTool->Options(Duplicates => 0);
400 # get current Verbose setting
402 $isVerbose = $exifTool->Options('Verbose');
403 # set a user parameter
405 $exifTool->Options(UserParam => 'MyParam=some value');
406 Inputs:
408 0) ExifTool object reference
409 1) Option parameter name (case-insensitive)
411 2) [optional] Option parameter value (may be undef to clear option)
413 3-N) [optional] Additional parameter/value pairs
415 Option Parameters:
417 Note that these API options may also be used in the exiftool
418 application via the command-line -api option.
419 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 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 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 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 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 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 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 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 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 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 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 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 CharsetPhotoshop
512 Internal encoding to assume for Photoshop IRB resource names.
513 Default is 'Latin'.
514 CharsetQuickTime
516 Internal encoding to assume for QuickTime strings stored with
517 an unspecified encoding. Default is 'MacRoman'.
518 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 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 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 Composite
547 Flag to generate Composite tags when extracting information.
548 Default is 1.
549 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 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 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 Note: To avoid loss of precision, the default coordinate
575 format is different when copying tags with
576 "SetNewValuesFromFile".
577 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 Duplicates
590 Flag to return values from tags with duplicate names when
591 extracting information. Default is 1.
592 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 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 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 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 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 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 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 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 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 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 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 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 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 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 GeoSpeedRef
724 Reference units for writing GPSSpeed when geotagging:
725 'K', 'k' or 'km/h' - km/h
727 'M', 'm' or 'mph' - mph
728 <anything else> - knots (default undef)
729 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 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 HexTagIDs
746 Return hexadecimal instead of decimal for the family 7 group
747 names of tags with numerical ID's.
748 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 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 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 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 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 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 LargeFileSupport
795 Flag to indicate that 64-bit file offsets are supported on this
796 system. Default is undef.
797 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 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 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 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 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 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 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 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 NoMultiExif
847 Raise error when attempting to write multi-segment EXIF in a
848 JPEG image. Default is undef.
849 NoPDFList
851 Flag to avoid splitting PDF list-type tag values into separate
852 items. Default is undef.
853 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 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 PrintConv
870 Flag to enable automatic print conversion. Also enables
871 inverse print conversion for writing. Default is 1.
872 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 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 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 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 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 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 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 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 Sort
939 Specifies order to sort tags in returned list:
940 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 Sort2
951 Secondary sort order used for tags within each group when Sort
952 is 'Group':
953 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 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 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 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 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 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 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 StructFormat
992 Format for serialized structures when reading/writing.
993 undef - Default ExifTool format
995 JSON - JSON format
996 JSONQ - JSON with quoted numerical values
997 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 TextOut
1005 Output file reference for Verbose and HtmlDump options.
1006 Default is \*STDOUT.
1007 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 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 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 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 Where PARAM is the user-defined parameter name (case
1034 insensitive).
1035 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 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 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 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 WriteMode
1070 Set tag write/create mode. Value is a string of one or more
1071 characters from list below. Default is 'wcg'.
1072 w - Write existing tags
1074 c - Create new tags
1075 g - create new Groups as necessary
1076 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 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 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 Return Values:
1094 The original value of the last specified parameter.
1095 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 $exifTool->ClearOptions();
1102 Inputs:
1104 0) ExifTool object reference
1105 Return Values:
1107 (none)
1108 ExtractInfo
1110 Extract all meta information from an image.
1111 $success = $exifTool->ExtractInfo('image.jpg', \%options);
1113 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 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 Return Value:
1130 1 if this was a recognized file format, 0 otherwise (and 'Error'
1131 tag set).
1132 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 # get image width and height only
1140 $info = $exifTool->GetInfo('ImageWidth', 'ImageHeight');
1141 # get all Error and Warning messages
1143 $info = $exifTool->GetInfo('Error', 'Warning');
1144 # get information for all tags in list (list updated with tags found)
1146 $info = $exifTool->GetInfo(\@ioTagList);
1147 # get all information in Author or Location groups
1149 $info = $exifTool->GetInfo({Group2 => ['Author', 'Location']});
1150 Inputs:
1152 Inputs are the same as "ExtractInfo" and "ImageInfo" except that an
1153 image can not be specified. Options in effect are:
1154 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 Return Value:
1160 Reference to information hash, the same as with "ImageInfo".
1161 The following options are effective in the call to "GetInfo":
1163 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 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 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 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 # add information to a source file, writing output to new file
1190 $exifTool->WriteInfo($srcfile, $dstfile);
1191 # create XMP data file from scratch
1193 $exifTool->WriteInfo(undef, $dstfile, 'XMP');
1194 # overwrite file (you do have backups, right?)
1196 $exifTool->WriteInfo($srcfile);
1197 Inputs:
1199 0) ExifTool object reference
1200 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 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 3) [optional] Destination file type. Ignored if a source is
1211 defined.
1212 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 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 $errorMessage = $exifTool->GetValue('Error');
1223 $warningMessage = $exifTool->GetValue('Warning');
1224 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 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 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 On Mac OS systems, the file resource fork is preserved if this
1246 routine is called with a source file name.
1247 The following ExifTool options are effective in the call to
1249 "WriteInfo":
1250 ByteOrder, Charset, CharsetEXIF, CharsetFileName, CharsetIPTC, Compact,
1252 Compress, FixBase, IgnoreMinorErrors, NoMultiExif, NoPDFList, Password,
1253 QuickTimeHandler, QuickTimePad, Verbose, WindowsWideFile and WriteMode.
1254 GetTagList
1256 Get a sorted list of tags from the specified information hash or tag
1257 list.
1258 @tags = $exifTool->GetTagList($info, 'Group0');
1260 Inputs:
1262 0) ExifTool object reference
1263 1) [optional] Information hash reference or tag list reference
1265 2) [optional] Sort order ('Input', 'File', 'Tag', 'Descr' or
1267 'Group#')
1268 3) [optional] Secondary sort order ('File', 'Tag' or 'Descr')
1270 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 Return Values:
1279 A list of tag keys in the specified order.
1280 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 @tags = $exifTool->GetFoundTags('File');
1287 Inputs:
1289 0) ExifTool object reference
1290 1) [optional] Sort order ('Input', 'File', 'Tag', 'Descr' or
1292 'Group#')
1293 2) [optional] Secondary sort order ('File', 'Tag' or 'Descr')
1295 If sort order is not specified, the sort order from the ExifTool
1297 options is used.
1298 Return Values:
1300 A list of tag keys in the specified order.
1301 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 @tags = $exifTool->GetRequestedTags();
1309 Inputs:
1311 (none)
1312 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 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 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 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 # 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 # 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 my @keywords = $exifTool->GetValue('Keywords', 'ValueConv');
1358 The following options are in effect when "GetValue" is called:
1360 Charset, CoordFormat, DateFormat, Escape, Filter, GlobalTimeShift,
1362 Lang, ListItem, ListJoin, PrintConv, QuickTimeUTC (conversion to local
1363 time), StrictDate and TimeZone.
1364 Inputs:
1366 0) ExifTool object reference
1367 1) Tag key, or case-sensitive tag name with optional group
1369 prefix(es)
1370 2) [optional] Value type: 'PrintConv', 'ValueConv', 'Both', 'Raw'
1372 or 'Rational'
1373 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 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 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 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 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 # set a new value for a tag (errors go to STDERR)
1409 $success = $exifTool->SetNewValue($tag, $value);
1410 # set a new value and capture any error message
1412 ($success, $errStr) = $exifTool->SetNewValue($tag, $value);
1413 # 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 # reset all values from previous calls to SetNewValue()
1419 $exifTool->SetNewValue();
1420 # delete a specific keyword
1422 $exifTool->SetNewValue('Keywords', $word, DelValue => 1);
1423 # 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 # add a keyword without replacing existing keywords in the file
1431 $exifTool->SetNewValue(Keywords => $word, AddValue => 1);
1432 # 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 # set a tag in a specific group
1440 $exifTool->SetNewValue(Headline => $val, Group => 'XMP');
1441 $exifTool->SetNewValue('XMP:Headline' => $val); # (equivalent)
1442 # shift original date/time back by 2.5 hours
1444 $exifTool->SetNewValue(DateTimeOriginal => '2:30', Shift => -1);
1445 # 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 # write tag by numerical value
1452 $exifTool->SetNewValue(Orientation => 6, Type => 'ValueConv');
1453 $exifTool->SetNewValue('Orientation#' => 6); # (equivalent)
1454 # delete all but EXIF tags
1456 $exifTool->SetNewValue('*'); # delete all...
1457 $exifTool->SetNewValue('EXIF:*', undef, Replace => 2); # ...but EXIF
1458 # write structured information as a HASH reference
1460 $exifTool->SetNewValue('XMP:Flash' => {
1461 mode => 'on',
1462 fired => 'true',
1463 return => 'not'
1464 });
1465 # write structured information as a serialized string
1467 $exifTool->SetNewValue('XMP:Flash'=>'{mode=on,fired=true,return=not}');
1468 (See <https://exiftool.org/struct.html#Serialize> for a description of
1470 the structure serialization technique.)
1471 Inputs:
1473 0) ExifTool object reference
1474 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 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 3-N) [optional] SetNewValue option/value pairs (see below).
1499 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 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 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 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 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 NoFlat
1537 Treat flattened tags as 'unsafe'.
1538 NoShortcut
1540 Disables default behaviour of looking up tag in shortcuts if
1541 not found otherwise.
1542 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 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 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 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 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 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 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 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 The following ExifTool options are effective in the call to
1601 "SetNewValue":
1602 Charset, DateFormat, Escape, IgnoreMinorErrors, Lang, ListJoin,
1604 ListSplit, PrintConv, QuickTimeUTC, StrictDate, TimeZone, Verbose and
1605 WriteMode.
1606 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 $rawVal = $exifTool->GetNewValue($tag);
1613 @rawVals = $exifTool->GetNewValue($tag);
1615 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 Inputs:
1621 0) ExifTool object reference
1622 1) Tag name (case sensitive, may be prefixed by family 0, 1 or 7
1624 group names, separated by colons)
1625 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 SetNewValuesFromFile
1633 A very powerful routine that sets new values for tags from information
1634 found in a specified file.
1635 # 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 # set all new values, preserving original groups
1642 $exifTool->SetNewValuesFromFile($srcFile, '*:*');
1643 # set specific information
1645 $exifTool->SetNewValuesFromFile($srcFile, @tags);
1646 # set new value from a different tag in specific group
1648 $exifTool->SetNewValuesFromFile($fp, 'XMP-dc:Subject<IPTC:Keywords');
1649 # add all IPTC keywords to XMP subject list
1651 $exifTool->SetNewValuesFromFile($fp, 'XMP-dc:Subject+<IPTC:Keywords');
1652 # set new value from an expression involving other tags
1654 $exifTool->SetNewValuesFromFile($file,
1655 'Comment<ISO=$ISO Aperture=$aperture Exposure=$shutterSpeed');
1656 # set keywords list from the values of multiple tags
1658 $exifTool->SetNewValuesFromFile($file, { Replace => 0 },
1659 'keywords<xmp:subject', 'keywords<filename');
1660 # 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 # 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 # set FileName from Model, translating questionable characters
1670 $exifTool->SetNewValuesFromFile($file,
1671 'filename<${model; tr(/\\\\?*:|"><)(_) }.jpg');
1672 Inputs:
1674 0) ExifTool object reference
1675 1) File name, file reference, or scalar reference
1677 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 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 SetNewValuesFromFile Options:
1728 The options are the same was for "SetNewValue", and are passed
1729 directly to "SetNewValue" internally, with a few exceptions:
1730 - 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 - The AddValue or DelValue option is set for individual tags if
1736 '+>' or '->' (or '+<' or '-<') are used.
1737 - The Group option is set for tags where a group name is given.
1739 - The Protected flag is set to 1 for individually specified tags.
1741 - The Type option also applies to extracted tags.
1743 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 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 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 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 The "Duplicates" option is always in effect for tags extracted from
1763 the source file using this routine.
1764 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 CountNewValues
1771 Return the total number of new values set.
1772 $numSet = $exifTool->CountNewValues();
1774 ($numSet, $numPseudo) = $exifTool->CountNewValues();
1775 Inputs:
1777 0) ExifTool object reference
1778 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 SaveNewValues
1787 Save state of new values to be later restored by "RestoreNewValues".
1788 $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 Inputs:
1796 0) ExifTool object reference
1797 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 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 Inputs:
1808 0) ExifTool object reference
1809 Return Value:
1811 None.
1812 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 $exifTool->SetAlternateFile(File1 => 'images/test1.jpg');
1820 Inputs:
1822 0) ExifTool object reference
1823 1) Family 8 group name, case insensitive (eg. 'File1', 'File2'...)
1825 2) Name of alternate input file, or undef to reset
1827 Return Values:
1829 1 on success, or 0 if the group name is invalid.
1830 SetFileModifyDate
1832 Write the filesystem modification or creation time from the new value
1833 of the FileModifyDate or FileCreateDate tag.
1834 $exifTool->SetNewValue(FileModifyDate => '2000:01:02 03:04:05-05:00',
1836 Protected => 1);
1837 $result = $exifTool->SetFileModifyDate($file);
1838 Inputs:
1840 0) ExifTool object reference
1841 1) File name
1843 2) [optional] Base time if applying shift (days before $^T)
1845 3) [optional] Tag to write: 'FileModifyDate' (default), or
1847 'FileCreateDate'
1848 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 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 The ability to write FileCreateDate is currently restricted to
1861 Windows systems only.
1862 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 $result = $exifTool->SetFileName($file);
1874 $result = $exifTool->SetFileName($file, $newName);
1875 Inputs:
1877 0) ExifTool object reference
1878 1) Current file name
1880 2) [optional] New file name
1882 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 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 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 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 $exifTool->SetNewGroups('XMP','EXIF','IPTC');
1907 Inputs:
1909 0) ExifTool object reference
1910 1-N) Groups in order of priority. If no groups are specified, the
1912 priorities are reset to the defaults.
1913 Return Value:
1915 None.
1916 GetNewGroups
1918 Get current group priority list.
1919 @groups = $exifTool->GetNewGroups();
1921 Inputs:
1923 0) ExifTool object reference
1924 Return Values:
1926 List of group names in order of write priority. Highest priority
1927 first.
1928 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 $id = $exifTool->GetTagID($tag);
1939 ($id, $lang) = $exifTool->GetTagID($tag);
1940 Inputs:
1942 0) ExifTool object reference
1943 1) Tag key
1945 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 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 Inputs:
1957 0) ExifTool object reference
1958 1) Tag key
1960 Return Values:
1962 A description for the specified tag.
1963 GetGroup
1965 Get group name(s) for a specified tag.
1966 # return family 0 group name (eg. 'EXIF');
1968 $group = $exifTool->GetGroup($tag, 0);
1969 # return all groups (eg. qw{EXIF IFD0 Author Main})
1971 @groups = $exifTool->GetGroup($tag);
1972 # return groups as a string (eg. 'Main:IFD0:Author')
1974 $group = $exifTool->GetGroup($tag, ':3:1:2');
1975 # return groups as a simplified string (eg. 'IFD0:Author')
1977 $group = $exifTool->GetGroup($tag, '3:1:2');
1978 Inputs:
1980 0) ExifTool object reference
1981 1) Tag key
1983 2) [optional] Group family number, or string of numbers separated
1985 by colons
1986 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 Notes:
1997 The group family numbers are currently available:
1998 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 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 Family 2 classifies information based on the logical category to
2026 which the information refers.
2027 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 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 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 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 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 Family 8 specifies the alternate file set from a call to
2065 "SetAlternateFile".
2066 See "GetAllGroups [static]" for complete lists of group names.
2068 GetGroups
2070 Get list of group names that exist in the specified information.
2071 @groups = $exifTool->GetGroups($info, 2);
2073 @groups = $exifTool->GetGroups('3:1');
2074 Inputs:
2076 0) ExifTool object reference
2077 1) [optional] Info hash ref (default is all extracted info)
2079 2) [optional] Group family number, or string of numbers (default 0)
2081 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 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 Inputs:
2095 0) ExifTool object reference
2096 Return Values:
2098 (none)
2099 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 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 AvailableOptions [static]
2115 Get a list of available API options. (See "Options" for option
2116 details.)
2117 Inputs:
2119 (none)
2120 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 my $opts = Image::ExifTool::<b>AvailableOptions</b>();
2127 foreach (@$opts) {
2128 my ($optionName, $defaultValue, $description) = @$_;
2129 ...
2130 }
2131 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 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 $tagName = Image::ExifTool::GetTagName($tag);
2141 Inputs:
2143 0) Tag key
2144 Return Value:
2146 Tag name. This is the same as the tag key but has the instance
2147 number removed.
2148 GetShortcuts [static]
2150 Get a list of shortcut tags.
2151 Inputs:
2153 (none)
2154 Return Values:
2156 List of shortcut tags (as defined in Image::ExifTool::Shortcuts).
2157 GetAllTags [static]
2159 Get list of all available tag names.
2160 @tagList = Image::ExifTool::GetAllTags($group);
2162 Inputs:
2164 0) [optional] Group name, or string of group names separated by
2165 colons
2166 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 GetWritableTags [static]
2174 Get list of all writable tag names.
2175 @tagList = Image::ExifTool::GetWritableTags($group);
2177 Inputs:
2179 0) [optional] Group name, or string of group names separated by
2180 colons
2181 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 GetAllGroups [static]
2190 Get list of all group names in specified family.
2191 @groupList = Image::ExifTool::GetAllGroups($family);
2193 Inputs:
2195 0) Group family number (0-7)
2196 Return Values:
2198 A list of all groups in the specified family in alphabetical order.
2199 Here is a complete list of groups for each of these families:
2201 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 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 Family 2 (Category):
2264 Audio, Author, Camera, Device, Document, ExifTool, Image, Location,
2265 Other, Preview, Printing, Time, Unknown, Video
2266 Family 3 (Document Number):
2268 Doc#, Main
2269 Family 4 (Instance Number):
2271 Copy#
2272 Family 5 (Metadata Path):
2274 eg. JPEG-APP1-IFD0-ExifIFD
2275 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 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 Family 8 (Alternate File):
2288 File#
2289 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 GetDeleteGroups [static]
2295 Get list of all deletable group names.
2296 @delGroups = Image::ExifTool::GetDeleteGroups();
2298 Inputs:
2300 None.
2301 Return Values:
2303 A list of deletable group names in alphabetical order. The current
2304 list of deletable group names is:
2305 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 To schedule a group for deletion, call "SetNewValue" with a tag
2317 name like 'EXIF:*' and an undefined tag value.
2318 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 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 GetFileType [static]
2332 Get type of file given file name.
2333 my $type = Image::ExifTool::GetFileType($filename);
2335 my $desc = Image::ExifTool::GetFileType($filename, 1);
2336 Inputs:
2338 0) [optional] File name (or just an extension)
2339 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 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 CanWrite [static]
2358 Can the specified file be written?
2359 my $writable = Image::ExifTool::CanWrite($filename);
2361 Inputs:
2363 0) File name or extension
2364 Return Value:
2366 True if ExifTool supports writing files of this type (based on the
2367 file extension).
2368 CanCreate [static]
2370 Can the specified file be created?
2371 my $creatable = Image::ExifTool::CanCreate($filename);
2373 Inputs:
2375 0) File name or extension
2376 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 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 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 Inputs:
2397 0) Destination tag table name
2398 1-N) Pairs of tag ID / tag information hash references for the new
2400 tags
2401 Return Value:
2403 The number of tags added.
2404 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
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 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 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 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 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 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 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 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 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 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 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 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 exiftool -tagsfromfile @ -iptc:all -codedcharacterset=utf8 a.jpg
2510 or from Windows Latin2 (cp1250) to UTF-8:
2512 exiftool -tagsfromfile @ -iptc:all -codedcharacterset=utf8 \
2514 -charset iptc=latin2 a.jpg
2515 and this command changes it back from UTF-8 to Windows Latin1 (cp1252):
2517 exiftool -tagsfromfile @ -iptc:all -codedcharacterset= a.jpg
2519 or to Windows Latin2:
2521 exiftool -tagsfromfile @ -iptc:all -codedcharacterset= \
2523 -charset iptc=latin2 a.jpg
2524 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 (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 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 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 JPEG Comment
2555 The encoding for the JPEG Comment (COM segment) is not specified, so
2556 ExifTool reads/writes this text without conversion.
2557 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 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 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 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 AIFF
2592 AIFF strings are assumed to be stored in MacRoman, and are converted
2593 according to the "Charset" option when reading.
2594 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 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 Vorbis
2609 Vorbis comments are stored as UTF-8, and are converted to the character
2610 set specified by the "Charset" option.
2611
2613 Copyright 2003-2023, Phil Harvey
2614 This library is free software; you can redistribute it and/or modify it
2616 under the same terms as Perl itself.
2617
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
2626 exiftool(1), Image::ExifTool::TagNames(3pm),
2627 Image::ExifTool::Shortcuts(3pm), Image::ExifTool::Shift(3pm),
2628 Image::Info(3pm), Image::MetaData::JPEG(3pm)
2629perl v5.36.1 2023-11-21 Image::ExifTool(3)