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 = new Image::ExifTool;
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 | DR4 r/w/c | JNG r/w | O r | RAW r/w
58 3FR r | DSS r | JP2 r/w | ODP r | RIFF r
59 3G2 r/w | DV r | JPEG r/w | ODS r | RSRC r
60 3GP r/w | DVB r/w | JSON r | ODT r | RTF r
61 A r | DVR-MS r | JXL r | OFR r | RW2 r/w
62 AA r | DYLIB r | K25 r | OGG r | RWL r/w
63 AAE r | EIP r | KDC r | OGV r | RWZ r
64 AAX r/w | EPS r/w | KEY r | ONP r | RM r
65 ACR r | EPUB r | LA r | OPUS r | SEQ r
66 AFM r | ERF r/w | LFP r | ORF r/w | SKETCH r
67 AI r/w | EXE r | LIF r | ORI r/w | SO r
68 AIFF r | EXIF r/w/c | LNK r | OTF r | SR2 r/w
69 APE r | EXR r | LRV r/w | PAC r | SRF r
70 ARQ r/w | EXV r/w/c | M2TS r | PAGES r | SRW r/w
71 ARW r/w | F4A/V r/w | M4A/V r/w | PBM r/w | SVG r
72 ASF r | FFF r/w | MACOS r | PCD r | SWF r
73 AVI r | FITS r | MAX r | PCX r | THM r/w
74 AVIF r/w | FLA r | MEF r/w | PDB r | TIFF r/w
75 AZW r | FLAC r | MIE r/w/ | PDF r/w | TORRENT r
76 BMP r | FLIF r/w | MIFF r c | PEF r/w | TTC r
77 BPG r | FLV r | MKA r | PFA r | TTF r
78 BTF r | FPF r | MKS r | PFB r | TXT r
79 CHM r | FPX r | MKV r | PFM r | VCF r
80 COS r | GIF r/w | MNG r/w | PGF r | VRD r/w/c
81 CR2 r/w | GPR r/w | MOBI r | PGM r/w | VSD r
82 CR3 r/w | GZ r | MODD r | PLIST r | WAV r
83 CRM r/w | HDP r/w | MOI r | PICT r | WDP r/w
84 CRW r/w | HDR r | MOS r/w | PMP r | WEBP r
85 CS1 r/w | HEIC r/w | MOV r/w | PNG r/w | WEBM r
86 CSV r | HEIF r/w | MP3 r | PPM r/w | WMA r
87 CZI r | HTML r | MP4 r/w | PPT r | WMV r
88 DCM r | ICC r/w/c | MPC r | PPTX r | WTV r
89 DCP r/w | ICS r | MPG r | PS r/w | WV r
90 DCR r | IDML r | MPO r/w | PSB r/w | X3F r/w
91 DFONT r | IIQ r/w | MQV r/w | PSD r/w | XCF r
92 DIVX r | IND r/w | MRC r | PSP r | XLS r
93 DJVU r | INSP r/w | MRW r/w | QTIF r/w | XLSX r
94 DLL r | INSV r | MXF r | R3D r | XMP r/w/c
95 DNG r/w | INX r | NEF r/w | RA r | ZIP r
96 DOC r | ISO r | NKSC r/w | RAF r/w |
97 DOCX r | ITC r | NRW r/w | RAM r |
98 DPX r | J2C r | NUMBERS r | RAR r |
99 Meta Information
101 ----------------------+----------------------+---------------------
102 EXIF r/w/c | CIFF r/w | Ricoh RMETA r
103 GPS r/w/c | AFCP r/w | Picture Info r
104 IPTC r/w/c | Kodak Meta r/w | Adobe APP14 r
105 XMP r/w/c | FotoStation r/w | MPF r
106 MakerNotes r/w/c | PhotoMechanic r/w | Stim r
107 Photoshop IRB r/w/c | JPEG 2000 r | DPX r
108 ICC Profile r/w/c | DICOM r | APE r
109 MIE r/w/c | Flash r | Vorbis r
110 JFIF r/w/c | FlashPix r | SPIFF r
111 Ducky APP12 r/w/c | QuickTime r | DjVu r
112 PDF r/w/c | Matroska r | M2TS r
113 PNG r/w/c | MXF r | PE/COFF r
114 Canon VRD r/w/c | PrintIM r | AVCHD r
115 Nikon Capture r/w/c | FLAC r | ZIP r
116 GeoTIFF r/w/c | ID3 r | (and more)
117
119 User-defined tags can be added via the ExifTool configuration file, or
120 by defining the %Image::ExifTool::UserDefined hash before calling any
121 ExifTool methods. See "ExifTool_config" in the ExifTool distribution
122 for more details.
123 By default ExifTool looks for a configuration file named
125 ".ExifTool_config" first in your home directory, then in the directory
126 of the application script, but a different directory may be specified
127 by setting the EXIFTOOL_HOME environment variable, or a different file
128 may be specified by setting the ExifTool "configFile" variable before
129 using Image::ExifTool. For example:
130 BEGIN { $Image::ExifTool::configFile = '/Users/phil/myconfig.cfg' }
132 use Image::ExifTool;
133 The configuration feature may also be disabled by setting "configFile"
135 to an empty string:
136 BEGIN { $Image::ExifTool::configFile = '' }
138 use Image::ExifTool;
139
141 Exports nothing by default, but "ImageInfo" and all static methods may
142 be exported with the ":Public" export list.
143
145 All ExifTool features are accessed through the methods of the public
146 interface listed below. Other Image::ExifTool methods and modules
147 should not be accessed directly because their interface may change with
148 future versions.
149 None of these methods should ever die or issue warnings to STDERR if
151 called with the proper arguments (with the exception of "SetNewValue"
152 which may send an error message to STDERR, but only when called in
153 scalar context). Error and warning messages that occur during
154 processing are stored in the values of the Error and Warning tags, and
155 are accessible via the "GetValue" method to retrieve a single Error or
156 Warning message, or "GetInfo" to retrieve any number of them.
157 The ExifTool methods are not thread safe.
159 new
161 Creates a new ExifTool object.
162 $exifTool = new Image::ExifTool;
164 One ExifTool object may be used to process many files, so creating
166 multiple ExifTool objects usually is not necessary.
167 Note that ExifTool uses AUTOLOAD to load non-member methods, so any
169 class using Image::ExifTool as a base class must define an AUTOLOAD
170 which calls Image::ExifTool::DoAutoLoad(). eg)
171 sub AUTOLOAD
173 {
174 Image::ExifTool::DoAutoLoad($AUTOLOAD, @_);
175 }
176 ImageInfo
178 Read image file and return meta information. This is the one step
179 function for retrieving meta information from an image. Internally,
180 "ImageInfo" calls "ExtractInfo" to extract the information, "GetInfo"
181 to generate the information hash, and "GetTagList" for the returned tag
182 list.
183 # return meta information for 2 tags only (procedural)
185 $info = ImageInfo($filename, $tag1, $tag2);
186 # return information about an open image file (object-oriented)
188 $info = $exifTool->ImageInfo(\*FILE);
189 # return information from image data in memory for specified tags
191 %options = (PrintConv => 0);
192 @tagList = qw(filename imagesize xmp:creator exif:* -ifd1:*);
193 $info = ImageInfo(\$imageData, \@tagList, \%options);
194 # extract information from an embedded thumbnail image
196 $info = ImageInfo('image.jpg', 'thumbnailimage');
197 $thumbInfo = ImageInfo($$info{ThumbnailImage});
198 Inputs:
200 "ImageInfo" is very flexible about the input arguments, and
201 interprets them based on their type. It may be called with one or
202 more arguments. The one required argument is either a SCALAR (the
203 image file name), a file reference (a reference to the image file)
204 or a SCALAR reference (a reference to the image in memory). Other
205 arguments are optional. The order of the arguments is not
206 significant, except that the first SCALAR is taken to be the file
207 name unless a file reference or scalar reference comes earlier in
208 the argument list.
209 Below is an explanation of how the "ImageInfo" function arguments
211 are interpreted:
212 ExifTool ref
214 "ImageInfo" may be called with an ExifTool object if desired.
215 Advantages of using the object-oriented form are that options
216 may be set before calling "ImageInfo", and the object may be
217 used afterward to access member functions. Must be the first
218 argument if used.
219 SCALAR
221 The first scalar argument is taken to be the file name unless
222 an earlier argument specified the image data via a file
223 reference (file ref) or data reference (SCALAR ref). The
224 remaining scalar arguments are names of tags for requested
225 information. All tags are returned if no tags are specified.
226 Tag names are case-insensitive and may be prefixed by optional
228 group names separated by colons. A group name may begin with a
229 family number (eg. '1IPTC:Keywords'), to restrict matches to a
230 specific family. In the tag name, a '?' matches any single
231 character and a '*' matches zero or more characters. Thus
232 'GROUP:*' represents all tags in a specific group. Wildcards
233 may not be used in group names, with the exception that a group
234 name of '*' may be used to extract all available instances of a
235 tag regardless of the "Duplicates" setting (eg.
236 '*:WhiteBalance'). Multiple groups may be specified (eg.
237 'EXIF:Time:*' extracts all EXIF Time tags). And finally, a
238 leading '-' indicates a tag to be excluded (eg. '-IFD1:*'), or
239 a trailing '#' causes the ValueConv value to be returned for
240 this tag.
241 Note that keys in the returned information hash and elements of
243 the returned tag list are not necessarily the same as these tag
244 names because group names are removed, the case may be changed,
245 and an instance number may be added. For this reason it is
246 best to use either the keys of the returned hash or the
247 elements of the returned tag list when accessing the tag
248 values.
249 See Image::ExifTool::TagNames for a complete list of ExifTool
251 tag names.
252 File ref
254 A reference to an open image file. If you use this method (or
255 a SCALAR reference) to access information in an image, the
256 FileName and Directory tags will not be returned. (Also, a
257 number of the File System tags will not be returned unless it
258 is a plain file.) Image processing begins at the current file
259 position, and on return the file position is unspecified. May
260 be either a standard filehandle, or a reference to a
261 File::RandomAccess object. Note that the file remains open and
262 must be closed by the caller after "ImageInfo" returns.
263 [Advanced: To allow a non-rewindable stream (eg. a network
265 socket) to be re-read after processing with ExifTool, first
266 wrap the file reference in a File::RandomAccess object, then
267 pass this object to "ImageInfo". The File::RandomAccess object
268 will buffer the file if necessary, and may be used to re-read
269 the file after "ImageInfo" returns.]
270 SCALAR ref
272 A reference to image data in memory.
273 ARRAY ref
275 Reference to a list of tag names. On entry, any elements in
276 the list are added to the list of requested tags. Tags with
277 names beginning with '-' are excluded. On return, this list is
278 updated to contain an ordered list of tag keys for the returned
279 information.
280 There will be 1:1 correspondence between the requested tags and
282 the returned tag keys only if the "Duplicates" option is 0 and
283 "Sort" is 'Input'. (With "Duplicates" enabled, there may be
284 more entries in the returned list of tag keys, and with other
285 "Sort" settings the entries may not be in the same order as
286 requested.) If a requested tag doesn't exist, a tag key is
287 still generated, but the tag value is undefined.
288 HASH ref
290 Reference to a hash containing the options settings valid for
291 this call only. See "Options" documentation below for a list
292 of available options. Options specified as arguments to
293 "ImageInfo" take precedence over "Options" settings.
294 Return Values:
296 "ImageInfo" returns a reference to a hash of tag-key/value pairs.
297 The tag keys are identifiers -- essentially case-sensitive tag
298 names with an appended instance number if multiple tags with the
299 same name were extracted from the image. Many of the ExifTool
300 functions require a tag key as an argument. Use "GetTagName
301 [static]" to get the tag name for a given tag key. Note that the
302 case of the tag names may not be the same as requested. Here is a
303 simple example to print out the information returned by
304 "ImageInfo":
305 foreach (sort keys %$info) {
307 print "$_ => $$info{$_}\n";
308 }
309 Values of the returned hash are usually simple scalars, but a
311 scalar reference is used to indicate binary data and an array
312 reference may be used to indicate a list. Also, a hash reference
313 may be returned if the "Struct" option is used. Lists of values
314 are joined by commas into a single string only if the PrintConv
315 option is enabled and the ListJoin option is enabled (which are the
316 defaults). Note that binary values are not necessarily extracted
317 unless specifically requested, or the Binary option is enabled and
318 the tag is not specifically excluded. If not extracted the value
319 is a reference to a string of the form "Binary data ##### bytes".
320 The code below gives an example of how to handle these return
322 values, as well as illustrating the use of other ExifTool
323 functions:
324 use Image::ExifTool;
326 my $exifTool = new Image::ExifTool;
327 $exifTool->Options(Unknown => 1);
328 my $info = $exifTool->ImageInfo('a.jpg');
329 my $group = '';
330 my $tag;
331 foreach $tag ($exifTool->GetFoundTags('Group0')) {
332 if ($group ne $exifTool->GetGroup($tag)) {
333 $group = $exifTool->GetGroup($tag);
334 print "---- $group ----\n";
335 }
336 my $val = $info->{$tag};
337 if (ref $val eq 'SCALAR') {
338 if ($$val =~ /^Binary data/) {
339 $val = "($$val)";
340 } else {
341 my $len = length($$val);
342 $val = "(Binary data $len bytes)";
343 }
344 }
345 printf("%-32s : %s\n", $exifTool->GetDescription($tag), $val);
346 }
347 Notes:
349 ExifTool returns all values as byte strings of encoded characters.
350 Perl wide characters are not used. See "CHARACTER ENCODINGS" for
351 details about the encodings. By default, most returned values are
352 encoded in UTF-8. For these, Encode::decode_utf8() may be used to
353 convert to a sequence of logical Perl characters.
354 As well as tags representing information extracted from the image,
356 the following Extra tags generated by ExifTool may be returned:
357 ExifToolVersion - The ExifTool version number.
359 Error - An error message if the image could not be processed.
361 Warning - A warning message if problems were encountered while
363 processing the image.
364 Options
366 Get/set ExifTool options. This function can be called to set the
367 default options for an ExifTool object. Options set this way are in
368 effect for all function calls but may be overridden by options passed
369 as arguments to some functions. Option names are not case sensitive.
370 The default option values may be changed by defining a
372 %Image::ExifTool::UserDefined::Options hash. See the ExifTool_config
373 file in the full ExifTool distribution for examples. A default of
374 undef has the same behaviour as a value of 0 for numerical options.
375 # exclude the 'OwnerName' tag from returned information
377 $exifTool->Options(Exclude => 'OwnerName');
378 # only get information in EXIF or MakerNotes groups
380 $exifTool->Options(Group0 => ['EXIF', 'MakerNotes']);
381 # ignore information from IFD1
383 $exifTool->Options(Group1 => '-IFD1');
384 # sort by groups in family 2, and extract unknown tags
386 $exifTool->Options(Sort => 'Group2', Unknown => 1);
387 # reset DateFormat option
389 $exifTool->Options(DateFormat => undef);
390 # do not extract duplicate tag names
392 $oldSetting = $exifTool->Options(Duplicates => 0);
393 # get current Verbose setting
395 $isVerbose = $exifTool->Options('Verbose');
396 # set a user parameter
398 $exifTool->Options(UserParam => 'MyParam=some value');
399 Inputs:
401 0) ExifTool object reference
402 1) Option parameter name (case-insensitive)
404 2) [optional] Option parameter value (may be undef to clear option)
406 3-N) [optional] Additional parameter/value pairs
408 Option Parameters:
410 Note that these API options may also be used in the exiftool
411 application via the command-line -api option.
412 Binary
414 Flag to extract the value data for all binary tags. Tag values
415 representing large binary data blocks (eg. ThumbnailImage) are
416 not necessarily extracted unless this option is set or the tag
417 is specifically requested by name. Default is undef.
418 BlockExtract
420 Flag to extract some directories (mentioned in the ExifTool tag
421 name documentation) as a block. Setting this to a value of 2
422 also prevents parsing the block to extract tags contained
423 within.
424 ByteOrder
426 The byte order for newly created EXIF segments when writing.
427 Note that if EXIF information already exists, the existing
428 order is maintained. Valid values are 'MM', 'II' and undef.
429 If ByteOrder is not defined (the default), then the maker note
430 byte order is used (if they are being copied), otherwise big-
431 endian ('MM') order is assumed. This can also be set via the
432 ExifByteOrder tag, but the ByteOrder option takes precedence if
433 both are set.
434 Charset
436 Character set for encoding character tag values passed to/from
437 ExifTool with code points above U+007F. Default is 'UTF8'.
438 Valid values are listed below, case is not significant:
439 Value Alias(es) Description
441 ----------- --------------- ----------------------------------
442 UTF8 cp65001, UTF-8 UTF-8 characters
443 Latin cp1252, Latin1 Windows Latin1 (West European)
444 Latin2 cp1250 Windows Latin2 (Central European)
445 Cyrillic cp1251, Russian Windows Cyrillic
446 Greek cp1253 Windows Greek
447 Turkish cp1254 Windows Turkish
448 Hebrew cp1255 Windows Hebrew
449 Arabic cp1256 Windows Arabic
450 Baltic cp1257 Windows Baltic
451 Vietnam cp1258 Windows Vietnamese
452 Thai cp874 Windows Thai
453 DOSLatinUS cp437 DOS Latin US
454 DOSLatin1 cp850 DOS Latin1
455 DOSCyrillic cp866 DOS Cyrillic
456 MacRoman cp10000, Roman Macintosh Roman
457 MacLatin2 cp10029 Macintosh Latin2 (Central Europe)
458 MacCyrillic cp10007 Macintosh Cyrillic
459 MacGreek cp10006 Macintosh Greek
460 MacTurkish cp10081 Macintosh Turkish
461 MacRomanian cp10010 Macintosh Romanian
462 MacIceland cp10079 Macintosh Icelandic
463 MacCroatian cp10082 Macintosh Croatian
464 Note that this option affects some types of information when
466 reading/writing the file and other types when getting/setting
467 tag values, so it must be defined for both types of access.
468 See the "CHARACTER ENCODINGS" section for more information
469 about the handling of special characters.
470 CharsetEXIF
472 Internal encoding to use for stored EXIF "ASCII" string values.
473 May also be set to undef to pass through EXIF "ASCII" values
474 without recoding. Set to "UTF8" to conform with the MWG
475 recommendation. Default is undef.
476 CharsetFileName
478 External character set used for file names passed to ExifTool
479 functions. When set in Windows, this triggers use of Windows
480 wide-character i/o library routines (requires Win32API::File).
481 Default is undef. May also be set to an empty string to avoid
482 "encoding not specified" warnings on Windows.
483 CharsetID3
485 Internal encoding to assume for ID3v1 strings. By the
486 specification ID3v1 strings should be encoded in ISO 8859-1
487 (essentially Latin), but some applications may use local
488 encoding instead. Default is 'Latin'.
489 CharsetIPTC
491 Fallback internal IPTC character set to assume if IPTC
492 information contains no CodedCharacterSet tag. Possible values
493 are the same as the "Charset" option. Default is 'Latin'.
494 Note that this option affects some types of information when
496 reading/writing the file and other types when getting/setting
497 tag values, so it must be defined for both types of access.
498 CharsetPhotoshop
500 Internal encoding to assume for Photoshop IRB resource names.
501 Default is 'Latin'.
502 CharsetQuickTime
504 Internal encoding to assume for QuickTime strings stored with
505 an unspecified encoding. Default is 'MacRoman'.
506 CharsetRIFF
508 Internal encoding to assume for strings in RIFF metadata (eg.
509 AVI and WAV files). The default value of 0 assumes "Latin"
510 encoding unless otherwise specified by the RIFF CSET chunk.
511 Set to undef to pass through strings without recoding. Default
512 is 0.
513 Compact
515 Comma-delimited list of settings for writing compact XMP.
516 Below is a list of available settings. Note that 'NoPadding'
517 effects only embedded XMP since padding is never written for
518 stand-alone XMP files. Also note that 'OneDesc' is not
519 recommended when writing XMP larger than 64 kB to a JPG file
520 because it interferes with ExifTool's technique of splitting
521 off large rdf:Description elements into the extended XMP. Case
522 is not significant for any of these options. Aliases are given
523 in brackets. Default is undef.
524 NoPadding - Avoid 2 kB of recommended padding at end of XMP (NoPad)
526 NoIndent - No spaces to indent lines (NoSpace, NoSpaces)
527 NoNewline - Avoid unnecessary newlines (NoNewlines)
528 Shorthand - Use XMP Shorthand format
529 OneDesc - Combine properties into a single rdf:Description (OneDescr)
530 AllSpace - Equivalent to 'NoPadding,NoIndent,NoNewline'
531 AllFormat - Equivalent to 'Shorthand,OneDesc'
532 All - Equivalent to 'AllSpace,AllFormat'
533 Composite
535 Flag to generate Composite tags when extracting information.
536 Default is 1.
537 Compress
539 Flag to write new values in compressed format if possible. Has
540 no effect unless Compress::Zlib is installed. Default is
541 undef.
542 CoordFormat
544 Format for printing GPS coordinates. This is a printf format
545 string with specifiers for degrees, minutes and seconds in that
546 order, however minutes and seconds may be omitted. If the
547 hemisphere is known, a reference direction (N, S, E or W) is
548 appended to each printed coordinate, but adding a "+" to the
549 first format specifier (eg. "%+.6f") prints a signed coordinate
550 instead. For example, the following table gives the output for
551 the same coordinate using various formats:
552 CoordFormat Example Output
554 ------------------- ------------------
555 q{%d deg %d' %.2f"} 54 deg 59' 22.80" (default for reading)
556 q{%d %d %.8f} 54 59 22.80000000 (default for copying)
557 q{%d deg %.4f min} 54 deg 59.3800 min
558 q{%.6f degrees} 54.989667 degrees
559 Note: To avoid loss of precision, the default coordinate
561 format is different when copying tags with
562 "SetNewValuesFromFile".
563 DateFormat
565 Format for printing date/time values. See "strftime" in the
566 POSIX package and <https://exiftool.org/filename.html#codes>
567 for details about the format string. If the date can not be
568 converted, the value is left unchanged unless the StrictDate
569 option is set. Timezones are ignored. The inverse conversion
570 (ie. when calling "SetNewValue") is performed only if
571 POSIX::strptime or Time::Piece is installed. The default
572 setting of undef causes date/time values to remain in standard
573 EXIF format (similar to a DateFormat of "%Y:%m:%d %H:%M:%S").
574 Duplicates
576 Flag to return values from tags with duplicate names when
577 extracting information. Default is 1.
578 Escape
580 Escape special characters in extracted values for HTML or XML.
581 Also unescapes HTML or XML character entities in input values
582 passed to "SetNewValue". Valid settings are 'HTML', 'XML' or
583 undef. Default is undef.
584 Exclude
586 Exclude specified tags from tags extracted from an image. The
587 option value is either a tag name or reference to a list of tag
588 names to exclude. The case of tag names is not significant.
589 This option is ignored for specifically requested tags. Tags
590 may also be excluded by preceding their name with a '-' in the
591 arguments to "ImageInfo".
592 ExtendedXMP
594 This setting affects the reading and editing of extended XMP in
595 JPEG images. According to the XMP specification, extended XMP
596 is only valid if it has the GUID specified by the
597 HasExtendedXMP tag, so by default ExifTool will ignore other
598 extended XMP, but this option allows full control over the
599 extended XMP to be extracted.
600 0 - Ignore all extended XMP
602 1 - Read extended XMP with valid GUID only (default)
603 2 - Read extended XMP with any GUID
604 <guid> - Read extended XMP with a specific GUID
605 ExtractEmbedded
607 Flag to extract information from embedded documents in EPS
608 files, embedded EPS information and JPEG and Jpeg2000 images in
609 PDF files, embedded MPF images in JPEG and MPO files, timed
610 metadata in videos, and the resource fork of Mac OS files. A
611 setting of 2 also causes the H264 video stream in MP4 files to
612 be parsed until the first SEI message is decoded, or 3 to parse
613 the entire H264 stream in MP4 videos and the entire M2TS file
614 to look for any unlisted program containing GPS metadata.
615 Default is undef.
616 FastScan
618 Flag to increase speed when reading files by avoiding
619 extraction of some types of metadata. With this option set to
620 1, ExifTool will not scan to the end of a JPEG image to check
621 for an AFCP, CanonVRD, FotoStation, PhotoMechanic, MIE or
622 PreviewImage trailer. This also stops the parsing after the
623 first comment in GIF images, and at the audio/video data of
624 RIFF-format files (AVI, WAV, etc), so any trailing metadata
625 (eg. XMP written by some utilities) may be missed. Also
626 disables input buffering for some types of files to reduce
627 memory usage when reading from a non-seekable stream, and
628 bypasses CRC validation for speed when writing PNG files. When
629 combined with the ScanForXMP option, prevents scanning for XMP
630 in recognized file types. With a value of 2, ExifTool will
631 also avoid extracting any EXIF MakerNote information, and will
632 stop parsing at the IDAT chunk of PNG images. (By the PNG
633 specification, metadata is allowed after IDAT, but ExifTool
634 always writes it before because some utilities will ignore it
635 otherwise.) When set to 3 or higher, only pseudo system tags
636 and FileType are generated. For 3, the file header is read to
637 provide an educated guess at FileType. For 4, the file is not
638 read at all and FileType is determined based on the file's
639 extension. For 5, generation of Composite tags is also
640 disabled (like setting "Composite" to 0). Default is undef.
641 Filter
643 Perl expression used to filter values for all tags. The
644 expression acts on the value of the Perl default variable ($_),
645 and changes the value of this variable as required. The
646 current ExifTool object may be accessed through $self. The
647 value is not changed if $_ is set to undef. List items are
648 filtered individually. Applies to all returned values unless
649 PrintConv option is disabled.
650 FilterW
652 Perl expression used to filter PrintConv values when writing.
653 The expression acts on the value of the Perl default variable
654 ($_), and changes the value of this variable as required. The
655 current ExifTool object may be accessed through $self. The tag
656 is not written if $_ is set to undef.
657 FixBase
659 Fix maker notes base offset. A common problem with image
660 editing software is that offsets in the maker notes are not
661 adjusted properly when the file is modified. This may cause
662 the wrong values to be extracted for some maker note entries
663 when reading the edited file. FixBase specifies an integer
664 value to be added to the maker notes base offset. It may also
665 be set to the empty string ('') for ExifTool will take its best
666 guess at the correct base, or undef (the default) for no base
667 adjustment.
668 GeoMaxIntSecs
670 Maximum interpolation time in seconds for geotagging.
671 Geotagging is treated as an extrapolation if the Geotime value
672 lies between two fixes in the same track which are separated by
673 a number of seconds greater than this. Otherwise, the
674 coordinates are calculated as a linear interpolation between
675 the nearest fixes on either side of the Geotime value. Set to
676 0 to disable interpolation and use the coordinates of the
677 nearest fix instead (provided it is within GeoMaxExtSecs,
678 otherwise geotagging fails). Default is 1800.
679 GeoMaxExtSecs
681 Maximum extrapolation time in seconds for geotagging.
682 Geotagging fails if the Geotime value lies outside a GPS track
683 by a number of seconds greater than this. Otherwise, for an
684 extrapolation the coordinates of the nearest fix are taken (ie.
685 it is assumed that you weren't moving during this period).
686 Default is 1800.
687 GeoMaxHDOP
689 Maximum Horizontal (2D) Dilution Of Precision for geotagging.
690 GPS fixes are ignored if the HDOP is greater than this.
691 Default is undef.
692 GeoMaxPDOP
694 Maximum Position (3D) Dilution Of Precision for geotagging.
695 GPS fixes are ignored if the PDOP is greater than this.
696 Default is undef.
697 GeoMinSats
699 Minimum number of satellites for geotagging. GPS fixes are
700 ignored if the number of acquired satellites is less than this.
701 Default is undef.
702 GeoSpeedRef
704 Reference units for writing GPSSpeed when geotagging:
705 'K', 'k' or 'km/h' - km/h
707 'M', 'm' or 'mph' - mph
708 <anything else> - knots (default undef)
709 GlobalTimeShift
711 Time shift to apply to all extracted date/time PrintConv
712 values. Does not affect ValueConv values. Value is a
713 date/time shift string (see Image::ExifTool::Shift(3pm)), with
714 a leading '-' for negative shifts. Default is undef.
715 Group#
717 Extract tags only for specified groups in family # (Group0
718 assumed if # not given). The option value may be a single
719 group name or a reference to a list of groups. Case is
720 significant in group names. Specify a group to be excluded by
721 preceding group name with a '-'. See "GetGroup" for a
722 description of group families, and "GetAllGroups [static]" for
723 lists of group names.
724 HexTagIDs
726 Return hexadecimal instead of decimal for the family 7 group
727 names of tags with numerical ID's.
728 HtmlDump
730 Dump information in hex to dynamic HTML web page. The value
731 may be 0-3 for increasingly larger limits on the maximum block
732 size. Default is 0. Output goes to the file specified by the
733 TextOut option (\*STDOUT by default).
734 HtmlDumpBase
736 Base for HTML dump offsets. If not defined, the EXIF/TIFF base
737 offset is used. Set to 0 for absolute offsets. Default is
738 undef.
739 IgnoreMinorErrors
741 Flag to ignore minor errors. Causes minor errors to be
742 downgraded to warnings, and minor warnings to be ignored. This
743 option is provided mainly to allow writing of files when minor
744 errors occur, but by ignoring some minor warnings the behaviour
745 of ExifTool may be changed to allow some questionable
746 operations to proceed (such as extracting thumbnail and preview
747 images even if they don't have a recognizable header). Minor
748 errors and warnings are denoted by "[minor]" at the start of
749 the message, or "[Minor]" (with a capital "M") for warnings
750 that affect processing when ignored.
751 Lang
753 Localized language for exiftool tag descriptions, etc.
754 Available languages are given by the Image::ExifTool::Lang
755 module names (eg. 'fr', 'zh_cn'). If the specified language
756 isn't available, the option is not changed. May be set to
757 undef to select the built-in default language. Default is
758 'en'.
759 LargeFileSupport
761 Flag to indicate that 64-bit file offsets are supported on this
762 system. Default is undef.
763 ListItem
765 Return only a specific item from list-type values. A value of
766 0 returns the first item in the list, 1 return the second item,
767 etc. Negative indices may also be used, with -1 representing
768 the last item in the list. Applies only to the top-level list
769 of nested lists. Default is undef to return all items in the
770 list.
771 ListJoin
773 Separator used to join the PrintConv value of multi-item List-
774 type tags into a single string. If not defined, multi-item
775 lists are returned as a list reference. Does not affect
776 ValueConv values. Default is ', '.
777 ListSplit
779 Regular expression used to split values of list-type tags into
780 individual items when writing. (eg. use ',\\s*' to split a
781 comma-separated list.) Split when writing either PrintConv or
782 ValueConv values. Default is undef.
783 MakerNotes
785 Option to extract MakerNotes and other writable subdirectories
786 (such as PrintIM) as a data block. Normally when the
787 MakerNotes are extracted they are rebuilt to include data
788 outside the boundaries of the original maker note data block,
789 but a value of 2 disables this feature. Possible values are:
790 0 - Do not extract writable subdirectories (same as default of undef)
792 1 - Extract and rebuild maker notes into self-contained block
793 2 - Extract without rebuilding maker notes
794 MDItemTags
796 Flag to extract the OS X metadata item tags (see the "mdls" man
797 page and "MacOS MDItem Tags" in Image::ExifTool::TagNames for
798 more information).
799 MissingTagValue
801 Value for missing tags in tag name expressions (or tags where
802 the advanced formatting expression returns undef). If not set,
803 a minor error is issued for missing values, or the value is set
804 to '' if "IgnoreMinorErrors" is set. Default is undef.
805 NoMultiExif
807 Raise error when attempting to write multi-segment EXIF in a
808 JPEG image. Default is undef.
809 NoPDFList
811 Flag to avoid splitting PDF list-type tag values into separate
812 items. Default is undef.
813 Password
815 Password for reading/writing password-protected PDF documents.
816 Ignored if a password is not required. Character encoding of
817 the password is determined by the value of the Charset option
818 at processing time. Default is undef.
819 PrintConv
821 Flag to enable automatic print conversion. Also enables
822 inverse print conversion for writing. Default is 1.
823 QuickTimeHandler
825 Flag set to add an 'mdir' Handler to a newly created Meta box
826 when adding QuickTime ItemList tags. Adobe Bridge does not add
827 this Handler, but it is commonly found in samples from other
828 software, and it has been reported that Apple QuickTime Player
829 and Photos.apps will ignore ItemList tags if this is missing.
830 Default is 1.
831 QuickTimePad
833 Flag to preserve the padding of some QuickTime atoms when
834 writing. QuickTime-based Canon CR3 files pad the values of
835 container atoms with null bytes. This padding is removed by
836 default when the file is rewritten, but setting this option to
837 1 adds padding to preserve the original atom size if the new
838 atom would be smaller than the original. Default is undef.
839 QuickTimeUTC
841 Flag set to assume that QuickTime date/time values are stored
842 as UTC, causing conversion to local time when they are
843 extracted and from local time when written. According to the
844 QuickTime specification date/time values should be UTC, but
845 many digital cameras store local time instead (presumably
846 because they don't know the time zone), so the default is to
847 not convert these times (except for Canon CR3 files, which
848 always use UTC times). This option also disables the
849 autodetection of incorrect time-zero offsets in QuickTime
850 date/time values, and enforces a time zero of 1904 as per the
851 QuickTime specification.
852 RequestAll
854 Flag to request all tags to be extracted. This causes some
855 tags to be generated which normally would not be unless
856 specifically requested (by passing the tag name to "ImageInfo"
857 or "ExtractInfo"). May be set to 2 or 3 to enable generation
858 of some additional tags as mentioned in the tag name
859 documentation. Default is undef.
860 RequestTags
862 List of additional tag and/or group names to request in the
863 next call to "ExtractInfo". This option is useful only for
864 tags/groups which aren't extracted unless specifically
865 requested. Value may be a list reference, a delimited string
866 of names (any delimiter is allowed), or undef to clear the
867 current RequestTags list. Groups are requested by adding a
868 colon after the name (eg. "MacOS:"). Names are converted to
869 lower case as they are added to the list. Default is undef.
870 SaveFormat
872 Flag to save EXIF/TIFF format type as the family 6 group name
873 when extracting information. Without this option set, the
874 family 6 group names are not generated. Default is undef. See
875 the "GetGroup" option for more details.
876 SavePath
878 Flag to save the metadata path as the family 5 group name when
879 extracting information. Without this option set, the family 5
880 group names are not generated. Default is undef. See the
881 "GetGroup" option for more details.
882 ScanForXMP
884 Flag to scan all files (even unrecognized formats) for XMP
885 information unless XMP was already found in the file. When
886 combined with the FastScan option, only unrecognized file types
887 are scanned for XMP. Default is undef.
888 Sort
890 Specifies order to sort tags in returned list:
891 Input - Sort in same order as input tag arguments (default)
893 File - Sort in order that tags were found in the file
894 Tag - Sort alphabetically by tag name
895 Descr - Sort by tag description (for current Lang setting)
896 Group# - Sort by tag group, where # is zero or more family
897 numbers separated by colons. If # is not specified,
898 Group0 is assumed. See GetGroup for a description
899 of group families.
900 Sort2
902 Secondary sort order used for tags within each group when Sort
903 is 'Group':
904 File - Sort in order tags were found in the file (default)
906 Tag - Sort alphabetically by tag name
907 Descr - Sort by tag description (for current Lang setting)
908 StrictDate
910 Flag to return undefined value for any date which can't be
911 converted when the DateFormat option is used. Default is
912 undef.
913 undef - Same as 0 for reading/writing, or 1 for copying
915 0 - Return date/time value unchanged if it can't be converted
916 1 - Return undef if date/time value can't be converted
917 When set to 1 while writing a PrintConv date/time value with
919 the DateFormat option set, the value is written only if
920 POSIX::strptime or Time::Piece is available and can
921 successfully convert the value.
922 For PNG CreationTime, a setting of 1 has the additional effect
924 of causing the date/time to be reformatted according to PNG 1.2
925 recommendation (RFC-1123) when writing, and a warning to be
926 issued for any non-standard value when reading (but note that
927 Windows may not recognize PNG date/time values in standard
928 format).
929 Struct
931 Flag to return XMP structures as hash references instead of
932 flattening into individual tags. Has no effect when writing
933 since both flattened and structured tags may always be written.
934 Possible values are:
935 undef - (default) Same as 0 for reading, 2 for copying
937 0 - Read/copy flattened tags
938 1 - Read/copy structured tags
939 2 - Read/copy both flattened and structured tags, but flag
940 flattened tags as 'unsafe' for copying
941 SystemTags
943 Flag to extract the following additional File System tags:
944 FileAttributes, FileDeviceNumber, FileInodeNumber,
945 FileHardLinks, FileUserID, FileGroupID, FileDeviceID,
946 FileBlockSize and FileBlockCount.
947 TextOut
949 Output file reference for Verbose and HtmlDump options.
950 Default is \*STDOUT.
951 TimeZone
953 Time zone for local date/time values. May be set to any valid
954 TZ string. Uses the system time zone if not specified.
955 Default is undef. (Requires POSIX::tzset, which may not be
956 available in Windows. A work-around in Windows is to "set
957 TZ=<zone>" before running ExifTool.)
958 Unknown
960 Flag to get the values of unknown tags. If set to 1, unknown
961 tags are extracted from EXIF (or other tagged-format)
962 directories. If set to 2, unknown tags are also extracted from
963 binary data blocks. Default is 0.
964 UserParam
966 Special option to set/get user-defined parameters. Useful to
967 allow external input into tag name expressions and ValueConv
968 logic. Valid UserParam values are:
969 PARAM - Get parameter
971 PARAM= - Clear parameter
972 PARAM^= - Set parameter to empty string
973 PARAM=VALUE - Set parameter
974 <hash ref> - Set entire UserParam hash lookup
975 undef - Clear all user parameters
976 Where PARAM is the user-defined parameter name (case
978 insensitive).
979 User-defined parameters may be accessed in tag name expressions
981 by prefixing the parameter name with a dollar sign just like
982 normal tags, or via the API by calling
983 "Options('UserParam','PARAM')". Appending a hash tag ("#") to
984 the parameter name also causes the parameter to be extracted as
985 a normal tag (in the UserParam group). If called without
986 additional arguments, "Options('UserParam')" returns a
987 reference to the hash of all user parameters (with lower-case
988 names).
989 Validate
991 Flag to perform extra validation metadata checks when reading,
992 causing extra warnings to be generated if problems are found.
993 Default is undef.
994 Verbose
996 Print verbose messages to file specified by TextOut option.
997 Value may be from 0 to 5 for increasingly verbose messages.
998 Default is 0. With the verbose option set, messages are
999 printed to the console as the file is parsed. Level 1 prints
1000 the tag names and raw values. Level 2 adds more details about
1001 the tags. Level 3 adds a hex dump of the tag data, but with
1002 limits on the number of bytes dumped. Levels 4 and 5 remove
1003 the dump limit on tag values and JPEG segment data
1004 respectively.
1005 WriteMode
1007 Set tag write/create mode. Value is a string of one or more
1008 characters from list below. Default is 'wcg'.
1009 w - Write existing tags
1011 c - Create new tags
1012 g - create new Groups as necessary
1013 The level of the group differs for different types of metadata.
1015 For XMP or IPTC this is the full XMP/IPTC block (the family 0
1016 group), but for EXIF this is the individual IFD (the family 1
1017 group). The 'w' and 'c' modes are tested only when
1018 "SetNewValue" is called, but the 'g' mode is also tested in
1019 "WriteInfo".
1020 XAttrTags
1022 Flag to extract the OS X extended attribute tags (see the
1023 "xattr" man page and "MacOS XAttr Tags" in
1024 Image::ExifTool::TagNames for more information).
1025 XMPAutoConv
1027 Flag to enable automatic conversion for unknown XMP tags with
1028 values that look like rational numbers or dates. Default is 1.
1029 Return Values:
1031 The original value of the last specified parameter.
1032 ClearOptions
1034 Reset all options to their default values. Loads user-defined default
1035 option values from the %Image::ExifTool::UserDefined::Options hash in
1036 the .ExifTool_config file if it exists.
1037 $exifTool->ClearOptions();
1039 Inputs:
1041 0) ExifTool object reference
1042 Return Values:
1044 (none)
1045 ExtractInfo
1047 Extract all meta information from an image.
1048 $success = $exifTool->ExtractInfo('image.jpg', \%options);
1050 Inputs:
1052 "ExtractInfo" takes exactly the same arguments as "ImageInfo". The
1053 only difference is that a list of tag keys is not returned if an
1054 ARRAY reference is given. The following options are effective in
1055 the call to "ExtractInfo":
1056 Binary, Charset, CharsetEXIF, CharsetFileName, CharsetID3,
1058 CharsetIPTC, CharsetPhotoshop, CharsetQuickTime, CharsetRIFF,
1059 Composite, ExtendedXMP, ExtractEmbedded, FastScan, FixBase,
1060 HtmlDump, HtmlDumpBase, IgnoreMinorErrors, Lang, LargeFileSupport,
1061 MakerNotes, MDItemTags, NoPDFList, Password, QuickTimeUTC (enforced
1062 1904 time zero), RequestAll, RequestTags, SaveFormat, SavePath,
1063 ScanForXMP, Struct, TextOut, Unknown, Verbose, XAttrTags and
1064 XMPAutoConv.
1065 Return Value:
1067 1 if this was a recognized file format, 0 otherwise (and 'Error'
1068 tag set).
1069 GetInfo
1071 "GetInfo" is called to return meta information after it has been
1072 extracted from the image by a previous call to "ExtractInfo" or
1073 "ImageInfo". This function may be called repeatedly after a single call
1074 to "ExtractInfo" or "ImageInfo".
1075 # get image width and height only
1077 $info = $exifTool->GetInfo('ImageWidth', 'ImageHeight');
1078 # get all Error and Warning messages
1080 $info = $exifTool->GetInfo('Error', 'Warning');
1081 # get information for all tags in list (list updated with tags found)
1083 $info = $exifTool->GetInfo(\@ioTagList);
1084 # get all information in Author or Location groups
1086 $info = $exifTool->GetInfo({Group2 => ['Author', 'Location']});
1087 Inputs:
1089 Inputs are the same as "ExtractInfo" and "ImageInfo" except that an
1090 image can not be specified. Options in effect are:
1091 Charset, CoordFormat, DateFormat, Duplicates, Escape, Exclude,
1093 Filter, Group#, GlobalTimeShift, Lang, ListItem, ListJoin,
1094 PrintConv, Sort (if a tag list reference is given) and StrictDate.
1095 Return Value:
1097 Reference to information hash, the same as with "ImageInfo".
1098 The following options are effective in the call to "GetInfo":
1100 Charset, CoordFormat, DateFormat, Duplicates, Escape, Exclude, Filter,
1102 Group#, GlobalTimeShift, Lang, ListItem, ListJoin, PrintConv,
1103 QuickTimeUTC (conversion to local time), Sort (if a tag list reference
1104 is given) and StrictDate.
1105 WriteInfo
1107 Write meta information to a file. The specified source file is
1108 rewritten to the same-type destination file with new information as
1109 specified by previous calls to "SetNewValue". The necessary segments
1110 and/or directories are created in the destination file as required to
1111 store the specified information. May be called repeatedly to write the
1112 same information to additional files without the need to call
1113 "SetNewValue" again.
1114 ExifTool queues all new values that are assigned via calls to
1116 "SetNewValue", then applies them to any number of files through one or
1117 more calls to "WriteInfo". These queued values may be accessed through
1118 "GetNewValue", and are completely separate from metadata extracted from
1119 files via "ExtractInfo" or "ImageInfo" and accessed through "GetInfo"
1120 or "GetValue".
1121 To be clear, it is NOT necessary to call "ExtractInfo" or "ImageInfo"
1123 before "WriteInfo". "WriteInfo" changes only metadata specified by
1124 previous calls to "SetNewValue".
1125 # add information to a source file, writing output to new file
1127 $exifTool->WriteInfo($srcfile, $dstfile);
1128 # create XMP data file from scratch
1130 $exifTool->WriteInfo(undef, $dstfile, 'XMP');
1131 # overwrite file (you do have backups, right?)
1133 $exifTool->WriteInfo($srcfile);
1134 Inputs:
1136 0) ExifTool object reference
1137 1) Source file name, file reference, scalar reference, or undef to
1139 create a file from scratch. A reference to a File::RandomAccess
1140 object is also allowed as a source, but in this case the
1141 destination is not optional.
1142 2) [optional] Destination file name, file reference, scalar
1144 reference to write to memory, or undef to overwrite the original
1145 file. May be '-' to write to stdout.
1146 3) [optional] Destination file type. Ignored if a source is
1148 defined.
1149 Return Value:
1151 1 if file was written OK, 2 if file was written but no changes
1152 made, 0 on file write error.
1153 If an error code is returned, an Error tag is set and
1155 GetValue('Error') can be called to obtain the error description. A
1156 Warning tag may be set even if this routine is successful. Calling
1157 WriteInfo clears any pre-existing Error and Warning tags.
1158 $errorMessage = $exifTool->GetValue('Error');
1160 $warningMessage = $exifTool->GetValue('Warning');
1161 Notes:
1163 The source file name may be undefined to create a file from scratch
1164 (currently only XMP, MIE, ICC, VRD, DR4, EXV and EXIF files can be
1165 created in this way -- see "CanCreate" for details). If undefined,
1166 the destination file type is required unless the type can be
1167 determined from the extension of the destination file name.
1168 If a destination file name is given, the specified file must not
1170 exist because an existing destination file will not be overwritten.
1171 Any new values for FileName, Directory or HardLink are ignored when
1172 a destination file name is specified.
1173 The destination file name may be undefined to overwrite the
1175 original file (make sure you have backups!). In this case, if a
1176 source file name is provided, a temporary file is created and
1177 renamed to replace the source file if no errors occurred while
1178 writing. Otherwise, if a source file reference or scalar reference
1179 is used, the image is first written to memory then copied back to
1180 replace the original if there were no errors.
1181 On Mac OS systems, the file resource fork is preserved if this
1183 routine is called with a source file name.
1184 The following ExifTool options are effective in the call to
1186 "WriteInfo":
1187 ByteOrder, Charset, CharsetEXIF, CharsetFileName, CharsetIPTC, Compact,
1189 Compress, FixBase, IgnoreMinorErrors, NoMultiExif, NoPDFList, Password,
1190 QuickTimeHandler, QuickTimePad, Verbose and WriteMode.
1191 GetTagList
1193 Get a sorted list of tags from the specified information hash or tag
1194 list.
1195 @tags = $exifTool->GetTagList($info, 'Group0');
1197 Inputs:
1199 0) ExifTool object reference
1200 1) [optional] Information hash reference or tag list reference
1202 2) [optional] Sort order ('Input', 'File', 'Tag', 'Descr' or
1204 'Group#')
1205 3) [optional] Secondary sort order ('File', 'Tag' or 'Descr')
1207 If the information hash or tag list reference is not provided, then
1209 the list of found tags from the last call to "ImageInfo",
1210 "ExtractInfo" or "GetInfo" is used instead, and the result is the
1211 same as if "GetFoundTags" was called. If sort order is not
1212 specified, the sort order is taken from the current options
1213 settings.
1214 Return Values:
1216 A list of tag keys in the specified order.
1217 GetFoundTags
1219 Get list of found tags in specified sort order. The found tags are the
1220 tags for the information obtained from the most recent call to
1221 "ImageInfo", "ExtractInfo" or "GetInfo" for this object.
1222 @tags = $exifTool->GetFoundTags('File');
1224 Inputs:
1226 0) ExifTool object reference
1227 1) [optional] Sort order ('Input', 'File', 'Tag', 'Descr' or
1229 'Group#')
1230 2) [optional] Secondary sort order ('File', 'Tag' or 'Descr')
1232 If sort order is not specified, the sort order from the ExifTool
1234 options is used.
1235 Return Values:
1237 A list of tag keys in the specified order.
1238 GetRequestedTags
1240 Get list of requested tags. These are the tags that were specified in
1241 the arguments of the most recent call to "ImageInfo", "ExtractInfo" or
1242 "GetInfo", including tags specified via a tag list reference. Shortcut
1243 tags are expanded in the list.
1244 @tags = $exifTool->GetRequestedTags();
1246 Inputs:
1248 (none)
1249 Return Values:
1251 List of requested tag keys in the same order that the tags were
1252 specified. Note that this list will be empty if tags were not
1253 specifically requested (ie. If extracting all tags).
1254 GetValue
1256 Get the value of a specified tag. The returned value is either the
1257 human-readable (PrintConv) value, the converted machine-readable
1258 (ValueConv) value, the original raw (Raw) value, or the original
1259 rational (Rational) value for rational formats. If the value type is
1260 not specified, the PrintConv value is returned if the PrintConv option
1261 is set, otherwise the ValueConv value is returned. The PrintConv
1262 values are same as the values returned by "ImageInfo" and "GetInfo" in
1263 the tag/value hash unless the PrintConv option is disabled.
1264 Tags which represent lists of multiple values (as may happen with
1266 'Keywords' for example) are handled specially. In scalar context, the
1267 returned PrintConv value for these tags is either a string of values or
1268 a list reference (depending on the ListJoin option setting), and the
1269 ValueConv value is always a list reference. But in list context,
1270 "GetValue" always returns the list itself.
1271 Note that "GetValue" requires a case-sensitive tag key as an argument.
1273 To retrieve tag information based on a case-insensitive tag name (with
1274 an optional group specifier), use "GetInfo" instead.
1275 # PrintConv example
1277 my $val = $exifTool->GetValue($tag);
1278 if (ref $val eq 'SCALAR') {
1279 print "$tag = (unprintable value)\n";
1280 } else {
1281 print "$tag = $val\n";
1282 }
1283 # ValueConv examples
1285 my $val = $exifTool->GetValue($tag, 'ValueConv');
1286 if (ref $val eq 'ARRAY') {
1287 print "$tag is a list of values\n";
1288 } elsif (ref $val eq 'SCALAR') {
1289 print "$tag represents binary data\n";
1290 } else {
1291 print "$tag is a simple scalar\n";
1292 }
1293 my @keywords = $exifTool->GetValue('Keywords', 'ValueConv');
1295 The following options are in effect when "GetValue" is called:
1297 Charset, CoordFormat, DateFormat, Escape, Filter, GlobalTimeShift,
1299 Lang, ListItem, ListJoin, PrintConv, QuickTimeUTC (conversion to local
1300 time), StrictDate and TimeZone.
1301 Inputs:
1303 0) ExifTool object reference
1304 1) Tag key, or case-sensitive tag name with optional group
1306 prefix(es)
1307 2) [optional] Value type: 'PrintConv', 'ValueConv', 'Both', 'Raw'
1309 or 'Rational'
1310 The default value type is 'PrintConv' if the PrintConv option is
1312 set, otherwise the default is 'ValueConv'. A value type of 'Both'
1313 returns both ValueConv and PrintConv values as a list. 'Rational'
1314 returns the raw rational value as a string fraction for rational
1315 types, or undef for other types.
1316 Return Values:
1318 The value of the specified tag. If the tag represents a list of
1319 multiple values and the ListJoin option is enabled then PrintConv
1320 returns a string of values, otherwise a reference to the list is
1321 returned in scalar context. The list itself is returned in list
1322 context. (Unless 'Both' values are requested, in which case two
1323 list references are returned, regardless of context.) Values may
1324 also be scalar references to binary data, or hash references if the
1325 "Struct" option is set.
1326 Note: It is possible for "GetValue" to return an undefined
1328 ValueConv or PrintConv value (or an empty list in list context)
1329 even if the tag exists, since it is possible for these conversions
1330 to yield undefined values. And the Rational value will be
1331 undefined for any non-rational tag. The Raw value should always
1332 exist if the tag exists.
1333 SetNewValue
1335 Set the new value for a tag. The routine may be called multiple times
1336 to set the values of many tags before using "WriteInfo" to write the
1337 new values to an image.
1338 For list-type tags (like Keywords), either call repeatedly with the
1340 same tag name for each value, or call with a reference to the list of
1341 values.
1342 # set a new value for a tag (errors go to STDERR)
1344 $success = $exifTool->SetNewValue($tag, $value);
1345 # set a new value and capture any error message
1347 ($success, $errStr) = $exifTool->SetNewValue($tag, $value);
1348 # delete information for specified tag if it exists in image
1350 # (also resets AddValue and DelValue options for this tag)
1351 $exifTool->SetNewValue($tag);
1352 # reset all values from previous calls to SetNewValue()
1354 $exifTool->SetNewValue();
1355 # delete a specific keyword
1357 $exifTool->SetNewValue('Keywords', $word, DelValue => 1);
1358 # set keywords (a list-type tag) with two new values
1360 $exifTool->SetNewValue(Keywords => 'word1');
1361 $exifTool->SetNewValue(Keywords => 'word2');
1362 # equivalent, but set both in one call using an array reference
1363 $exifTool->SetNewValue(Keywords => ['word1','word2']);
1364 # add a keyword without replacing existing keywords in the file
1366 $exifTool->SetNewValue(Keywords => $word, AddValue => 1);
1367 # conditionally add a tag if it didn't exist before,
1369 # or replace it if it had a specified value ("old value")
1370 $exifTool->SetNewValue(Description => '', DelValue => 1);
1371 $exifTool->SetNewValue(Description => 'old value', DelValue => 1);
1372 $exifTool->SetNewValue(Description => 'new value');
1373 # set a tag in a specific group
1375 $exifTool->SetNewValue(Headline => $val, Group => 'XMP');
1376 $exifTool->SetNewValue('XMP:Headline' => $val); # (equivalent)
1377 # shift original date/time back by 2.5 hours
1379 $exifTool->SetNewValue(DateTimeOriginal => '2:30', Shift => -1);
1380 # write a tag only if it had a specific value
1382 # (the order of the following calls is not significant)
1383 $exifTool->SetNewValue(Title => $oldVal, DelValue => 1);
1384 $exifTool->SetNewValue(Title => $newVal);
1385 # write tag by numerical value
1387 $exifTool->SetNewValue(Orientation => 6, Type => 'ValueConv');
1388 $exifTool->SetNewValue('Orientation#' => 6); # (equivalent)
1389 # delete all but EXIF tags
1391 $exifTool->SetNewValue('*'); # delete all...
1392 $exifTool->SetNewValue('EXIF:*', undef, Replace => 2); # ...but EXIF
1393 # write structured information as a HASH reference
1395 $exifTool->SetNewValue('XMP:Flash' => {
1396 mode => 'on',
1397 fired => 'true',
1398 return => 'not'
1399 });
1400 # write structured information as a serialized string
1402 $exifTool->SetNewValue('XMP:Flash'=>'{mode=on,fired=true,return=not}');
1403 (See <https://exiftool.org/struct.html#Serialize> for a description of
1405 the structure serialization technique.)
1406 Inputs:
1408 0) ExifTool object reference
1409 1) [optional] Tag key or tag name, or undef to clear all new
1411 values. The tag name may be prefixed by one or more family 0, 1 or
1412 2 group names with optional leading family numbers, separated by
1413 colons (eg. 'EXIF:Artist', 'XMP:Time:*'), which is equivalent to
1414 using a Group option argument. Also, a '#' may be appended to the
1415 tag name (eg. 'EXIF:Orientation#'), with the same effect as setting
1416 Type to 'ValueConv'. Wildcards ('*' and '?') may be used in the
1417 tag name to assign or delete multiple tags simultaneously. A tag
1418 name of '*' is special when deleting information, and will delete
1419 an entire group even if some individual tags in the group are not
1420 writable, but only if a single family 0 or 1 group is specified
1421 (otherwise the tags are deleted individually). Use
1422 "GetDeleteGroups" to get a list of deletable group names, and see
1423 Image::ExifTool::TagNames for a complete list of tag names.
1424 2) [optional] New value for tag. Undefined to delete tag from
1426 file. May be a scalar, scalar reference, list reference to set a
1427 list of values, or hash reference for a structure. Integer values
1428 may be specified as a hexadecimal string (with a leading '0x'), and
1429 simple rational values may be specified in fractional form (eg.
1430 '4/10'). Structure tags may be specified either as a hash
1431 reference or a serialized string (see the last two examples above).
1432 3-N) [optional] SetNewValue option/value pairs (see below).
1434 SetNewValue Options:
1436 AddValue
1437 Specifies that the value be added to an existing list in a file
1438 rather than overwriting the existing values. Valid settings
1439 are 0 (overwrite any existing tag value), 1 (add to an existing
1440 list and warn for non-list tags) or 2 (add to existing list and
1441 overwrite non-list tags). Default is 0.
1442 DelValue
1444 Delete existing tag from a file if it has the specified value.
1445 For list-type tags this deletes a specified item from the list.
1446 For non-list tags this may be used to conditionally replace a
1447 tag by providing a new value in a separate call to SetNewValue
1448 (see examples above). For structured tags, the entire
1449 structure is deleted/replaced only if all of the specified
1450 fields match the existing structure. Option values are 0 or 1.
1451 Default is 0.
1452 EditGroup
1454 Create tags in existing groups only. Don't create new group.
1455 Valid values are 0 and 1. Effectively removes the 'g' from the
1456 ExifTool WriteMode option for this tag only. Default is 0.
1457 EditOnly
1459 Edit tag only if it already exists. Don't create new tag.
1460 Valid values are 0 and 1. Effectively removes the 'c' from the
1461 ExifTool WriteMode option for this tag only. Default is 0.
1462 Group
1464 Specifies group name where tag should be written. This option
1465 is superseded by any group specified in the tag name. If not
1466 specified, tag is written to highest priority group as
1467 specified by "SetNewGroups". May be one or more family 0, 1 or
1468 2 groups with optional leading family number, separated by
1469 colons. Case is not significant.
1470 NoFlat
1472 Treat flattened tags as 'unsafe'.
1473 NoShortcut
1475 Disables default behaviour of looking up tag in shortcuts if
1476 not found otherwise.
1477 Protected
1479 Bit mask for tag protection levels to write. Bit 0x01 allows
1480 writing of 'unsafe' tags (ie. tags not copied automatically via
1481 "SetNewValuesFromFile"). Bit 0x02 allows writing of
1482 'protected' tags, and should only be used internally by
1483 ExifTool. See Image::ExifTool::TagNames, for a list of tag
1484 names indicating 'unsafe' and 'protected' tags. Default is 0.
1485 ProtectSaved
1487 Avoid setting new values which were saved after the Nth call to
1488 "SaveNewValues". Has no effect on unsaved values, or values
1489 saved before Nth call. Option value is N. Default is undef.
1490 Replace
1492 Flag to replace the previous new values for this tag (ie.
1493 replace the values set in previous calls to "SetNewValue").
1494 This option is most commonly used to replace previously-set new
1495 values for list-type tags. Valid values are 0 (set new value
1496 normally -- adds to new values for list-type tags), 1 (reset
1497 any previous new values before setting new value) or 2 (reset
1498 previous new values only; new value argument is ignored).
1499 Default is 0.
1500 Shift
1502 Shift the tag by the specified value. Currently only date/time
1503 tags and tags with numerical values may be shifted. Undefined
1504 for no shift, 1 for a positive shift, or -1 for a negative
1505 shift. A value of 0 causes a positive shift to be applied if
1506 the tag is shiftable and AddValue is set, or a negative shift
1507 for date/time tags only if DelValue is set. Default is undef.
1508 See Image::ExifTool::Shift(3pm) for more information.
1509 Type
1511 The type of value being set. Valid values are PrintConv,
1512 ValueConv or Raw. Default is PrintConv if the "PrintConv"
1513 Option is set, otherwise ValueConv.
1514 Return Values:
1516 In scalar context, returns the number of tags set and error
1517 messages are printed to STDERR. In list context, returns the
1518 number of tags set, and the error string (which is undefined if
1519 there was no error).
1520 Notes:
1522 When deleting groups of tags, the Replace option may be used to
1523 exclude specific groups from a mass delete. However, this
1524 technique may not be used to exclude individual tags from a group
1525 delete (unless a family 2 group was specified in the delete).
1526 Instead, use "SetNewValuesFromFile" to recover the values of
1527 individual tags after deleting a group.
1528 When deleting all tags from a JPEG image, the APP14 "Adobe"
1530 information is not deleted by default because doing so may affect
1531 the appearance of the image. However, this information may be
1532 deleted by specifying it explicitly, either by group (with
1533 'Adobe:*') or as a block (with 'Adobe').
1534 The following ExifTool options are effective in the call to
1536 "SetNewValue":
1537 Charset, DateFormat, Escape, IgnoreMinorErrors, Lang, ListJoin,
1539 ListSplit, PrintConv, QuickTimeUTC, StrictDate, TimeZone, Verbose and
1540 WriteMode.
1541 GetNewValue
1543 Get the new Raw value for a tag. This is the value set by
1544 "SetNewValue" this is queued to be written to file. List-type tags may
1545 return multiple values in list context.
1546 $rawVal = $exifTool->GetNewValue($tag);
1548 @rawVals = $exifTool->GetNewValue($tag);
1550 Inputs:
1552 0) ExifTool object reference
1553 1) Tag name (case sensitive, may be prefixed by family 0, 1 or 7
1555 group names, separated by colons)
1556 Return Values:
1558 List of new Raw tag values, or first value in list when called in
1559 scalar context. The list may be empty either if the tag isn't
1560 being written, or if it is being deleted (ie. if "SetNewValue" was
1561 called without a value).
1562 SetNewValuesFromFile
1564 A very powerful routine that sets new values for tags from information
1565 found in a specified file.
1566 # set new values from all information in a file...
1568 my $info = $exifTool->SetNewValuesFromFile($srcFile);
1569 # ...then write these values to another image
1570 my $result = $exifTool->WriteInfo($file2, $outFile);
1571 # set all new values, preserving original groups
1573 $exifTool->SetNewValuesFromFile($srcFile, '*:*');
1574 # set specific information
1576 $exifTool->SetNewValuesFromFile($srcFile, @tags);
1577 # set new value from a different tag in specific group
1579 $exifTool->SetNewValuesFromFile($fp, 'XMP-dc:Subject<IPTC:Keywords');
1580 # add all IPTC keywords to XMP subject list
1582 $exifTool->SetNewValuesFromFile($fp, 'XMP-dc:Subject+<IPTC:Keywords');
1583 # set new value from an expression involving other tags
1585 $exifTool->SetNewValuesFromFile($file,
1586 'Comment<ISO=$ISO Aperture=$aperture Exposure=$shutterSpeed');
1587 # set keywords list from the values of multiple tags
1589 $exifTool->SetNewValuesFromFile($file, { Replace => 0 },
1590 'keywords<xmp:subject', 'keywords<filename');
1591 # copy all EXIF information, preserving the original IFD
1593 # (without '*.*<' tags would be copied to the preferred EXIF IFD)
1594 $exifTool->SetNewValuesFromFile($file, '*:*<EXIF:*');
1595 # copy all tags with names starting with "gps" (note: this is
1597 # different than "gps:*" because it will also copy XMP GPS tags)
1598 $exifTool->SetNewValuesFromFile($file, 'gps*');
1599 # set FileName from Model, translating questionable characters
1601 $exifTool->SetNewValuesFromFile($file,
1602 'filename<${model; tr(/\\\\?*:|"><)(_) }.jpg');
1603 Inputs:
1605 0) ExifTool object reference
1606 1) File name, file reference, or scalar reference
1608 2-N) [optional] List of tag names to set or options hash
1610 references. All writable tags are set if none are specified. The
1611 tag names are not case sensitive, and may be prefixed by one or
1612 more family 0, 1, 2 or 7 group names with optional leading family
1613 numbers, separated by colons (eg. 'exif:iso'). A leading '-'
1614 indicates tags to be excluded (eg. '-comment'), or a trailing '#'
1615 causes the ValueConv value to be copied (same as setting the Type
1616 option to 'ValueConv' for this tag only). Wildcards ('*' and '?')
1617 may be used in the tag name. A tag name of '*' is commonly used
1618 when a group is specified to copy all tags in the group (eg.
1619 'XMP:*'). A special feature allows tag names of the form
1620 'DSTTAG<SRCTAG' (or 'SRCTAG>DSTTAG') to be specified to copy
1621 information to a tag with a different name or a specified group.
1622 Both 'SRCTAG' and 'DSTTAG' may contain wildcards and/or be prefixed
1623 by a group name (eg. 'fileModifyDate<modifyDate' or 'xmp:*<*'),
1624 and/or suffixed by a '#' to disable print conversion. Copied tags
1625 may also be added or deleted from a list with arguments of the form
1626 'DSTTAG+<SRCTAG' or 'DSTTAG-<SRCTAG'. Tags are evaluated in order,
1627 so exclusions apply only to tags included earlier in the list. An
1628 extension of this feature allows the tag value to be set from a
1629 string containing tag names with leading '$' symbols (eg.
1630 'Comment<the file is $filename'). Braces '{}' may be used around
1631 the tag name to separate it from subsequent text, and a '$$' is
1632 used to to represent a '$' symbol. The behaviour for missing tags
1633 in expressions is defined by the "MissingTagValue" option. The tag
1634 value may be modified via changes to the default input variable
1635 ($_) in a Perl expression placed inside the braces and after a
1636 semicolon following the tag name (see the last example above). A
1637 '@' may be added after the tag name (before the semicolon) to make
1638 the expression act on individual list items instead of the
1639 concatenated string for list-type tags. Braces within the
1640 expression must be balanced. Multiple options hash references may
1641 be passed to set different options for different tags. Options
1642 apply to subsequent tags in the argument list.
1643 By default, this routine will commute information between same-
1645 named tags in different groups, allowing information to be
1646 translated between images with different formats. This behaviour
1647 may be modified by specifying a group name for extracted tags (even
1648 if '*' is used as a group name), in which case the information is
1649 written to the original group, unless redirected to a different
1650 group. When '*' is used for a group name, by default the family 1
1651 group of the original tag is preserved, but a different family may
1652 be specified with a leading family number. (For example,
1653 specifying '*:*' copies all information while preserving the
1654 original family 1 groups, while '0*:*' preserves the family 0
1655 group.)
1656 SetNewValuesFromFile Options:
1658 The options are the same was for "SetNewValue", and are passed
1659 directly to "SetNewValue" internally, with a few exceptions:
1660 - The Replace option defaults to 1 instead of 0 as with
1662 "SetNewValue".
1663 - The AddValue or DelValue option is set for individual tags if
1665 '+>' or '->' (or '+<' or '-<') are used.
1666 - The Group option is set for tags where a group name is given.
1668 - The Protected flag is set to 1 for individually specified tags.
1670 - The Type option also applies to extracted tags.
1672 Return Values:
1674 A hash of information that was set successfully. May include
1675 Warning or Error entries if there were problems reading the input
1676 file.
1677 Notes:
1679 The PrintConv option applies to this routine, but it normally
1680 should be left on to provide more reliable transfer of information
1681 between groups.
1682 If a preview image exists, it is not copied. The preview image
1684 must be transferred separately if desired, in a separate call to
1685 "WriteInfo"
1686 When simply copying all information between files of the same type,
1688 it is usually desirable to preserve the original groups by
1689 specifying '*:*' for the tags to set.
1690 The "Duplicates" option is always in effect for tags extracted from
1692 the source file using this routine.
1693 The "Struct" option is enabled by default for tags extracted by
1695 this routine. This allows the hierarchy of complex structures to
1696 be preserved when copying, but the Struct option may be set to 0 to
1697 override this behaviour and copy as flattened tags instead.
1698 CountNewValues
1700 Return the total number of new values set.
1701 $numSet = $exifTool->CountNewValues();
1703 ($numSet, $numPseudo) = $exifTool->CountNewValues();
1704 Inputs:
1706 0) ExifTool object reference
1707 Return Values:
1709 In scalar context, returns the total number of tags with new values
1710 set. In list context, also returns the number of "pseudo" tag
1711 values which have been set. "Pseudo" tags are tags like FileName
1712 and FileModifyDate which are not contained within the file and can
1713 be changed without rewriting the file.
1714 SaveNewValues
1716 Save state of new values to be later restored by "RestoreNewValues".
1717 $exifTool->SaveNewValues(); # save state of new values
1719 $exifTool->SetNewValue(ISO => 100); # set new value for ISO
1720 $exifTool->WriteInfo($src, $dst1); # write ISO + previous new values
1721 $exifTool->RestoreNewValues(); # restore previous new values
1722 $exifTool->WriteInfo($src, $dst2); # write previous new values only
1723 Inputs:
1725 0) ExifTool object reference
1726 Return Value:
1728 Count of the number of times this routine has been called (N) since
1729 the last time the new values were reset.
1730 RestoreNewValues
1732 Restore new values to the settings that existed when "SaveNewValues"
1733 was last called. May be called repeatedly after a single call to
1734 "SaveNewValues". See "SaveNewValues" above for an example.
1735 Inputs:
1737 0) ExifTool object reference
1738 Return Value:
1740 None.
1741 SetFileModifyDate
1743 Write the filesystem modification or creation time from the new value
1744 of the FileModifyDate or FileCreateDate tag.
1745 $exifTool->SetNewValue(FileModifyDate => '2000:01:02 03:04:05-05:00',
1747 Protected => 1);
1748 $result = $exifTool->SetFileModifyDate($file);
1749 Inputs:
1751 0) ExifTool object reference
1752 1) File name
1754 2) [optional] Base time if applying shift (days before $^T)
1756 3) [optional] Tag to write: 'FileModifyDate' (default), or
1758 'FileCreateDate'
1759 Return Value:
1761 1 if the time was changed, 0 if nothing was done, or -1 if there
1762 was an error setting the time.
1763 Notes:
1765 Equivalent to, but more efficient than calling "WriteInfo" when
1766 only the FileModifyDate or FileCreateDate tag has been set. If a
1767 timezone is not specified, local time is assumed. When shifting,
1768 the time of the original file is used unless the optional base time
1769 is specified.
1770 The ability to write FileCreateDate is currently restricted to
1772 Windows systems only.
1773 SetFileName
1775 Set the file name and directory, or create a hard link. If not
1776 specified, the new file name is derived from the new values of the
1777 FileName and Directory tags, or from the HardLink or SymLink tag if
1778 creating a link. If the FileName tag contains a '/', then the file is
1779 renamed into a new directory. If FileName ends with '/', then it is
1780 taken as a directory name and the file is moved into the new directory.
1781 The new value for the Directory tag takes precedence over any directory
1782 specified in FileName.
1783 $result = $exifTool->SetFileName($file);
1785 $result = $exifTool->SetFileName($file, $newName);
1786 Inputs:
1788 0) ExifTool object reference
1789 1) Current file name
1791 2) [optional] New file name
1793 3) [optional] 'HardLink' or 'SymLink' to create a hard or symbolic
1795 link instead of renaming the file, or 'Test' to test renaming
1796 feature by printing the old and new names instead of changing
1797 anything.
1798 Return Value:
1800 1 on success, 0 if nothing was done, or -1 if there was an error
1801 renaming the file or creating the link.
1802 Notes:
1804 Will not overwrite existing files. New directories are created as
1805 necessary. If the file is successfully renamed, the new file name
1806 may be accessed via $$exifTool{NewName}.
1807 SetNewGroups
1809 Set the order of the preferred groups when adding new information. In
1810 subsequent calls to "SetNewValue", new information will be created in
1811 the first valid group of this list. This has an impact only if the
1812 group is not specified when calling "SetNewValue" and if the tag name
1813 exists in more than one group. The default order is EXIF, IPTC, XMP,
1814 MakerNotes, QuickTime, Photoshop, ICC_Profile, CanonVRD, Adobe. Any
1815 family 0 group name may be used. Case is not significant.
1816 $exifTool->SetNewGroups('XMP','EXIF','IPTC');
1818 Inputs:
1820 0) ExifTool object reference
1821 1-N) Groups in order of priority. If no groups are specified, the
1823 priorities are reset to the defaults.
1824 Return Value:
1826 None.
1827 GetNewGroups
1829 Get current group priority list.
1830 @groups = $exifTool->GetNewGroups();
1832 Inputs:
1834 0) ExifTool object reference
1835 Return Values:
1837 List of group names in order of write priority. Highest priority
1838 first.
1839 GetTagID
1841 Get the ID for the specified tag. The ID is the IFD tag number in EXIF
1842 information, the property name in XMP information, or the data offset
1843 in a binary data block. For some tags, such as Composite tags where
1844 there is no ID, an empty string is returned. In list context, also
1845 returns a language code for the tag if available and different from the
1846 default language (eg. with alternate language entries for XMP "lang-
1847 alt" tags).
1848 $id = $exifTool->GetTagID($tag);
1850 ($id, $lang) = $exifTool->GetTagID($tag);
1851 Inputs:
1853 0) ExifTool object reference
1854 1) Tag key
1856 Return Values:
1858 In scalar context, returns the tag ID or '' if there is no ID for
1859 this tag. In list context, returns the tag ID (or '') and the
1860 language code (or undef).
1861 GetDescription
1863 Get description for specified tag. This function will always return a
1864 defined value. In the case where the description doesn't exist, one is
1865 generated from the tag name.
1866 Inputs:
1868 0) ExifTool object reference
1869 1) Tag key
1871 Return Values:
1873 A description for the specified tag.
1874 GetGroup
1876 Get group name(s) for a specified tag.
1877 # return family 0 group name (eg. 'EXIF');
1879 $group = $exifTool->GetGroup($tag, 0);
1880 # return all groups (eg. qw{EXIF IFD0 Author Main})
1882 @groups = $exifTool->GetGroup($tag);
1883 # return groups as a string (eg. 'Main:IFD0:Author')
1885 $group = $exifTool->GetGroup($tag, ':3:1:2');
1886 # return groups as a simplified string (eg. 'IFD0:Author')
1888 $group = $exifTool->GetGroup($tag, '3:1:2');
1889 Inputs:
1891 0) ExifTool object reference
1892 1) Tag key
1894 2) [optional] Group family number, or string of numbers separated
1896 by colons
1897 Return Values:
1899 Group name (or '' if tag has no group). If no group family is
1900 specified, "GetGroup" returns the name of the group in family 0
1901 when called in scalar context, or the names of groups for all
1902 families in list context. Returns a string of group names
1903 separated by colons if the input group family contains a colon.
1904 The string is simplified to remove a leading 'Main:' and adjacent
1905 identical group names unless the family string begins with a colon.
1906 Notes:
1908 The group family numbers are currently available:
1909 0) Information Type (eg. EXIF, XMP, IPTC)
1911 1) Specific Location (eg. IFD0, XMP-dc)
1912 2) Category (eg. Author, Time)
1913 3) Document Number (eg. Main, Doc1, Doc3-2)
1914 4) Instance Number (eg. Copy1, Copy2, Copy3...)
1915 5) Metadata Path (eg. JPEG-APP1-IFD0-ExifIFD)
1916 6) EXIF/TIFF Format (eg. int8u, int32u, undef, string)
1917 7) Tag ID (eg. ID-271, ID-rights, ID-a9aut)
1918 Families 0 and 1 are based on the file structure, and are similar
1920 except that family 1 is more specific and sub-divides some groups
1921 to give more detail about the specific location where the
1922 information was found. For example, the EXIF group is split up
1923 based on the specific IFD (Image File Directory), the MakerNotes
1924 group is divided into groups for each manufacturer, and the XMP
1925 group is separated based on the XMP namespace prefix. Note that
1926 only common XMP namespaces are listed in the GetAllGroups
1927 documentation, but additional namespaces may be present in some XMP
1928 data. Also note that the 'XMP-xmp...' group names may appear in
1929 the older form 'XMP-xap...' since these names evolved as the XMP
1930 standard was developed. The ICC_Profile group is broken down to
1931 give information about the specific ICC_Profile tag from which
1932 multiple values were extracted. As well, information extracted
1933 from the ICC_Profile header is separated into the ICC-header group.
1934 Family 2 classifies information based on the logical category to
1936 which the information refers.
1937 Family 3 gives the document number for tags extracted from embedded
1939 documents, or 'Main' for tags from the main document. (See the
1940 "ExtractEmbedded" option for extracting tags from embedded
1941 documents.) Nested sub-documents (if they exist) are indicated by
1942 numbers separated with dashes in the group name, to an arbitrary
1943 depth. (eg. 'Doc2-3-1' is the 1st sub-sub-document of the 3rd sub-
1944 document of the 2nd embedded document of the main file.) Document
1945 numbers are also used to differentiate samples for timed metadata
1946 in videos.
1947 Family 4 provides a method for differentiating tags when multiple
1949 tags exist with the same name in the same location. The primary
1950 instance of a tag (the tag extracted when the Duplicates option is
1951 disabled and no group is specified) has no family 4 group name, but
1952 additional instances have family 4 group names of 'Copy1', 'Copy2',
1953 'Copy3', etc. For convenience, the primary tag may also be
1954 accessed using a group name of 'Copy0'.
1955 Family 5 is experimental, and gives the complete path for the
1957 metadata in the file. Generated only if the "SavePath" option is
1958 used when extracting.
1959 Family 6 is currently used only for EXIF/TIFF metadata, and gives
1961 the format type of the extracted value. Generated only if the
1962 "SaveFormat" option is used when extracting.
1963 Family 7 is used for tag ID's. The group names are the actual tag
1965 ID's, with a leading "ID-" string. Non-numerical ID's have
1966 characters other than [-_A-Za-z0-9] converted to hex. Numerical
1967 tag ID's are returned in hex if the "HexTagIDs" option is set,
1968 otherwise decimal is used. When specifying a family 7 group name,
1969 numerical ID's may be in hex or decimal, and non-numerical ID's may
1970 or may not have characters other than [-_A-Za-z0-9] converted to
1971 hex. Note that unlike other group names, the tag ID's of family 7
1972 group names are case sensitive (but the leading "ID-" is not).
1973 See "GetAllGroups [static]" for complete lists of group names.
1975 GetGroups
1977 Get list of group names that exist in the specified information.
1978 @groups = $exifTool->GetGroups($info, 2);
1980 @groups = $exifTool->GetGroups('3:1');
1981 Inputs:
1983 0) ExifTool object reference
1984 1) [optional] Info hash ref (default is all extracted info)
1986 2) [optional] Group family number, or string of numbers (default 0)
1988 Return Values:
1990 List of group names in alphabetical order. If information hash is
1991 not specified, the group names are returned for all extracted
1992 information. See "GetGroup" for an description of family numbers
1993 and family number strings.
1994 BuildCompositeTags
1996 Builds composite tags from required tags. The composite tags are
1997 convenience tags which are derived from the values of other tags. This
1998 routine is called automatically by "ImageInfo" and "ExtractInfo" if the
1999 Composite option is set.
2000 Inputs:
2002 0) ExifTool object reference
2003 Return Values:
2005 (none)
2006 Notes:
2008 Tag values are calculated in alphabetical order unless a tag
2009 Require's or Desire's another composite tag, in which case the
2010 calculation is deferred until after the other tag is calculated.
2011 Composite tags may need to read data from the image for their value
2013 to be determined, and for these "BuildCompositeTags" must be called
2014 while the image is available. This is only a problem if
2015 "ImageInfo" is called with a filename (as opposed to a file
2016 reference or scalar reference) since in this case the file is
2017 closed before "ImageInfo" returns. Here the Composite option may
2018 be used so that "BuildCompositeTags" is called from within
2019 "ImageInfo", before the file is closed.
2020 GetTagName [static]
2022 Get name of tag from tag key. This is a convenience function that
2023 strips the embedded instance number, if it exists, from the tag key.
2024 Note: "static" in the heading above indicates that the function does
2026 not require an ExifTool object reference as the first argument. All
2027 functions documented below are also static.
2028 $tagName = Image::ExifTool::GetTagName($tag);
2030 Inputs:
2032 0) Tag key
2033 Return Value:
2035 Tag name. This is the same as the tag key but has the instance
2036 number removed.
2037 GetShortcuts [static]
2039 Get a list of shortcut tags.
2040 Inputs:
2042 (none)
2043 Return Values:
2045 List of shortcut tags (as defined in Image::ExifTool::Shortcuts).
2046 GetAllTags [static]
2048 Get list of all available tag names.
2049 @tagList = Image::ExifTool::GetAllTags($group);
2051 Inputs:
2053 0) [optional] Group name, or string of group names separated by
2054 colons
2055 Return Values:
2057 A list of all available tags in alphabetical order, or all tags in
2058 a specified group or intersection of groups. The group name is
2059 case insensitive, and any group in families 0-2 may be used except
2060 for EXIF family 1 groups (ie. the specific IFD).
2061 GetWritableTags [static]
2063 Get list of all writable tag names.
2064 @tagList = Image::ExifTool::GetWritableTags($group);
2066 Inputs:
2068 0) [optional] Group name, or string of group names separated by
2069 colons
2070 Return Values:
2072 A list of all writable tags in alphabetical order. These are the
2073 tags for which values may be set through "SetNewValue". If a group
2074 name is given, returns only writable tags in specified group(s).
2075 The group name is case insensitive, and any group in families 0-2
2076 may be used except for EXIF family 1 groups (ie. the specific IFD).
2077 GetAllGroups [static]
2079 Get list of all group names in specified family.
2080 @groupList = Image::ExifTool::GetAllGroups($family);
2082 Inputs:
2084 0) Group family number (0-7)
2085 Return Values:
2087 A list of all groups in the specified family in alphabetical order.
2088 Here is a complete list of groups for each of these families:
2090 Family 0 (Information Type):
2092 AFCP, AIFF, APE, APP0, APP1, APP11, APP12, APP13, APP14, APP15,
2093 APP3, APP4, APP5, APP6, APP8, ASF, Audible, CanonVRD, Composite,
2094 DICOM, DNG, DV, DjVu, Ducky, EXE, EXIF, ExifTool, FITS, FLAC, FLIR,
2095 File, Flash, FlashPix, Font, FotoStation, GIF, GIMP, GeoTiff,
2096 GoPro, H264, HTML, ICC_Profile, ID3, IPTC, ISO, ITC, JFIF, JPEG,
2097 JSON, JUMBF, Jpeg2000, LNK, Leaf, Lytro, M2TS, MIE, MIFF, MNG, MOI,
2098 MPC, MPEG, MPF, MXF, MakerNotes, Matroska, Meta, Ogg, OpenEXR,
2099 Opus, PDF, PICT, PLIST, PNG, PSP, Palm, Parrot, PanasonicRaw,
2100 PhotoCD, PhotoMechanic, Photoshop, PostScript, PrintIM, QuickTime,
2101 RAF, RIFF, RSRC, RTF, Radiance, Rawzor, Real, Red, SVG, SigmaRaw,
2102 Stim, Theora, Torrent, Trailer, UserParam, VCard, Vorbis, WTV, XML,
2103 XMP, ZIP
2104 Family 1 (Specific Location):
2106 AC3, AFCP, AIFF, APE, ASF, AVI1, Adobe, AdobeCM, AdobeDNG, Apple,
2107 Audible, CBOR, CIFF, CameraIFD, Canon, CanonCustom, CanonRaw,
2108 CanonVRD, Casio, Chapter#, Composite, DICOM, DJI, DNG, DV, DjVu,
2109 DjVu-Meta, Ducky, EPPIM, EXE, EXIF, ExifIFD, ExifTool, FITS, FLAC,
2110 FLIR, File, Flash, FlashPix, Font, FotoStation, FujiFilm, FujiIFD,
2111 GE, GIF, GIMP, GPS, GeoTiff, GlobParamIFD, GoPro, GraphConv, H264,
2112 HP, HTC, HTML, HTML-dc, HTML-ncc, HTML-office, HTML-prod,
2113 HTML-vw96, HTTP-equiv, ICC-chrm, ICC-clrt, ICC-header, ICC-meas,
2114 ICC-meta, ICC-view, ICC_Profile, ICC_Profile#, ID3, ID3v1,
2115 ID3v1_Enh, ID3v2_2, ID3v2_3, ID3v2_4, IFD0, IFD1, IPTC, IPTC#, ISO,
2116 ITC, Insta360, InteropIFD, ItemList, JFIF, JFXX, JPEG, JPEG-HDR,
2117 JPS, JSON, JUMBF, JVC, Jpeg2000, KDC_IFD, Keys, Kodak,
2118 KodakBordersIFD, KodakEffectsIFD, KodakIFD, KyoceraRaw, LNK, Leaf,
2119 LeafSubIFD, Leica, Lyrics3, Lytro, M2TS, MAC, MIE-Audio, MIE-
2120 Camera, MIE-Canon, MIE-Doc, MIE-Extender, MIE-Flash, MIE-GPS, MIE-
2121 Geo, MIE-Image, MIE-Lens, MIE-Main, MIE-MakerNotes, MIE-Meta, MIE-
2122 Orient, MIE-Preview, MIE-Thumbnail, MIE-UTM, MIE-Unknown, MIE-
2123 Video, MIFF, MNG, MOBI, MOI, MPC, MPEG, MPF0, MPImage, MS-DOC, MXF,
2124 MacOS, MakerNotes, MakerUnknown, Matroska, MediaJukebox, Meta,
2125 MetaIFD, Microsoft, Minolta, MinoltaRaw, Motorola, NITF, Nikon,
2126 NikonCapture, NikonCustom, NikonScan, NikonSettings, NineEdits,
2127 Nintendo, Ocad, Ogg, Olympus, OpenEXR, Opus, PDF, PICT, PNG, PNG-
2128 pHYs, PSP, Palm, Panasonic, PanasonicRaw, Pentax, PhaseOne,
2129 PhotoCD, PhotoMechanic, Photoshop, PictureInfo, PostScript,
2130 PreviewIFD, PrintIM, ProfileIFD, Qualcomm, QuickTime, RAF, RAF2,
2131 RIFF, RMETA, RSRC, RTF, Radiance, Rawzor, Real, Real-CONT, Real-
2132 MDPR, Real-PROP, Real-RA3, Real-RA4, Real-RA5, Real-RJMD, Reconyx,
2133 Red, Ricoh, SPIFF, SR2, SR2DataIFD, SR2SubIFD, SRF#, SVG, Samsung,
2134 Sanyo, Scalado, Sigma, SigmaRaw, Sony, SonyIDC, Stim, SubIFD,
2135 System, Theora, Torrent, Track#, UserData, UserParam, VCalendar,
2136 VCard, Version0, Vorbis, WTV, XML, XMP, XMP-DICOM, XMP-Device, XMP-
2137 GAudio, XMP-GDepth, XMP-GFocus, XMP-GImage, XMP-GPano, XMP-
2138 GSpherical, XMP-LImage, XMP-MP, XMP-MP1, XMP-PixelLive, XMP-aas,
2139 XMP-acdsee, XMP-album, XMP-apple-fi, XMP-aux, XMP-cc, XMP-cell,
2140 XMP-creatorAtom, XMP-crs, XMP-dc, XMP-dex, XMP-digiKam, XMP-drone-
2141 dji, XMP-dwc, XMP-exif, XMP-exifEX, XMP-expressionmedia, XMP-
2142 extensis, XMP-fpv, XMP-getty, XMP-ics, XMP-iptcCore, XMP-iptcExt,
2143 XMP-lr, XMP-mediapro, XMP-microsoft, XMP-mwg-coll, XMP-mwg-kw, XMP-
2144 mwg-rs, XMP-pdf, XMP-pdfx, XMP-photomech, XMP-photoshop, XMP-plus,
2145 XMP-pmi, XMP-prism, XMP-prl, XMP-prm, XMP-pur, XMP-rdf, XMP-swf,
2146 XMP-tiff, XMP-x, XMP-xmp, XMP-xmpBJ, XMP-xmpDM, XMP-xmpMM, XMP-
2147 xmpNote, XMP-xmpPLUS, XMP-xmpRights, XMP-xmpTPg, ZIP, iTunes
2148 Family 2 (Category):
2150 Audio, Author, Camera, Device, Document, ExifTool, Image, Location,
2151 Other, Preview, Printing, Time, Unknown, Video
2152 Family 3 (Document Number):
2154 Doc#, Main
2155 Family 4 (Instance Number):
2157 Copy#
2158 Family 5 (Metadata Path):
2160 eg. JPEG-APP1-IFD0-ExifIFD
2161 Family 6 (EXIF/TIFF Format):
2163 int8u, string, int16u, int32u, rational64u, int8s, undef, int16s,
2164 int32s, rational64s, float, double, ifd, unicode, complex, int64u,
2165 int64s, ifd64
2166 Family 7 (Tag ID):
2168 ID-xxx (Where xxx is the tag ID. Numerical ID's are returned in
2169 hex with a leading "0x" if the HexTagIDs option is set, or decimal
2170 otherwise. Characters in non-numerical ID's which are not valid in
2171 a group name are returned as 2 hex digits.)
2172 Note: This function may also be called as an ExifTool member function
2174 to allow the HexTagIDs option to be set when retrieving family 7 group
2175 names.
2176 GetDeleteGroups [static]
2178 Get list of all deletable group names.
2179 @delGroups = Image::ExifTool::GetDeleteGroups();
2181 Inputs:
2183 None.
2184 Return Values:
2186 A list of deletable group names in alphabetical order. The current
2187 list of deletable group names is:
2188 Adobe, AFCP, APP0, APP1, APP10, APP11, APP12, APP13, APP14, APP15,
2190 APP2, APP3, APP4, APP5, APP6, APP7, APP8, APP9, Audio, Author,
2191 Camera, CanonVRD, CIFF, Document, Ducky, EXIF, ExifIFD, ExifTool,
2192 File, FlashPix, FotoStation, GlobParamIFD, GPS, ICC_Profile, IFD0,
2193 IFD1, Image, Insta360, InteropIFD, IPTC, ItemList, JFIF, Jpeg2000,
2194 Keys, Location, MakerNotes, Meta, MetaIFD, Microsoft, MIE, MPF,
2195 NikonCapture, Other, PDF, PDF-update, PhotoMechanic, Photoshop,
2196 PNG, PNG-pHYs, Preview, PrintIM, Printing, QuickTime, RMETA, RSRC,
2197 SubIFD, Time, Trailer, UserData, Video, XML, XML-*, XMP, XMP-*
2198 To schedule a group for deletion, call "SetNewValue" with a tag
2200 name like 'EXIF:*' and an undefined tag value.
2201 Deleting a family 0 or 1 group will delete the entire corresponding
2203 block of metadata, but deleting a family 2 group (eg. Audio,
2204 Author, Camera, etc.) deletes the individual tags belonging to
2205 that category.
2206 The 'Trailer' group allows all trailers in JPEG and TIFF-format
2208 images to be deleted at once, including unknown trailers. Note
2209 that the JPEG "APP" groups are special, and are used only to delete
2210 application segments which are not associated with another
2211 deletable group. For example, deleting 'APP14:*' will delete other
2212 APP14 segments, but not the APP14 "Adobe" segment.
2213 GetFileType [static]
2215 Get type of file given file name.
2216 my $type = Image::ExifTool::GetFileType($filename);
2218 my $desc = Image::ExifTool::GetFileType($filename, 1);
2219 Inputs:
2221 0) [optional] File name (or just an extension)
2222 1) [optional] Flag to return a description instead of a type.
2224 Default is undef. Set to 0 to also return types of recognized but
2225 unsupported files (otherwise the return value for unsupported files
2226 is undef), or 1 to return descriptions.
2227 Return Value:
2229 A string, based on the file extension, which indicates the basic
2230 format of the file. Note that some files may be based on other
2231 formats (like many RAW image formats are based on TIFF). In list
2232 context, may return more than one file type if the file may be
2233 based on different formats. Returns undef if files with this
2234 extension are not yet supported by ExifTool. Returns a list of
2235 extensions for all supported file types if no input extension is
2236 specified (or all recognized file types if the description flag is
2237 set to 0). Returns a more detailed description of the specific file
2238 format when the description flag is set.
2239 CanWrite [static]
2241 Can the specified file be written?
2242 my $writable = Image::ExifTool::CanWrite($filename);
2244 Inputs:
2246 0) File name or extension
2247 Return Value:
2249 True if ExifTool supports writing files of this type (based on the
2250 file extension).
2251 CanCreate [static]
2253 Can the specified file be created?
2254 my $creatable = Image::ExifTool::CanCreate($filename);
2256 Inputs:
2258 0) File name or extension
2259 Return Value:
2261 True if ExifTool can create files with this extension from scratch.
2262 Currently, this can only be done with XMP, MIE, ICC, VRD, DR4, EXV
2263 and EXIF files.
2264 AddUserDefinedTags [static]
2266 Add user-defined tags to an existing tag table at run time. This
2267 differs from the usual technique of creating user-defined tags via the
2268 %Image::ExifTool::UserDefined hash (see the ExifTool_config file in the
2269 Image::ExifTool distribution) because it allows tags to be added after
2270 a tag table has been initialized.
2271 use Image::ExifTool ':Public';
2273 my %tags = (
2274 TestTagID1 => { Name => 'TestTagName1' },
2275 TestTagID2 => { Name => 'TestTagName2' },
2276 );
2277 my $num = AddUserDefinedTags('Image::ExifTool::PDF::Info', %tags);
2278 Inputs:
2280 0) Destination tag table name
2281 1-N) Pairs of tag ID / tag information hash references for the new
2283 tags
2284 Return Value:
2286 The number of tags added.
2287 Notes
2289 Pre-existing tags with the same ID will be replaced in the
2290 destination table. See lib/Image/ExifTool/README in the full
2291 distribution for full details on the elements of the tag
2292 information hash.
2293
2295 Certain meta information formats allow coded character sets other than
2296 plain ASCII. When reading, most known encodings are converted to the
2297 external character set according to the "Charset" option, or to UTF-8
2298 by default. When writing, the inverse conversions are performed.
2299 Alternatively, special characters may be converted to/from HTML
2300 character entities with the "Escape" HTML option.
2301 A distinction is made between the external character set visible via
2303 the ExifTool API, and the internal character used to store text in the
2304 metadata of a file. These character sets may be specified separately
2305 as follows:
2306 External Character Sets:
2308 The encoding for tag values passed to/from ExifTool API functions
2309 is set via the "Charset" option, which is 'UTF8' by default.
2310 The encoding of file names is specified via the "CharsetFileName"
2312 option. By default, "CharsetFileName" is not defined, and file
2313 names passed to ExifTool are used directly in calls to the system
2314 i/o routines (which expect UTF-8 strings on Mac/Linux, but default
2315 to the system code page on Windows). In this mode on Windows a
2316 warning is issued if a file name contains special characters, but
2317 this warning may be avoided by setting "CharsetFileName" to an
2318 empty string. Setting "CharsetFileName" to any other value causes
2319 file names to be converted from the specified encoding to one
2320 appropriate for the system. In Windows this also has the effect of
2321 activating Unicode filename support via the special Windows wide-
2322 character i/o routines if Win32API::File is available.
2323 Internal Character Sets:
2325 The encodings used to store strings in the various metadata
2326 formats. These encodings may be changed for certain types of
2327 metadata via the "CharsetEXIF", "CharsetID3", "CharsetIPTC",
2328 "CharsetPhotoshop", "CharsetQuickTime" and "CharsetRIFF" options.
2329 Values are returned as byte strings of encoded characters. Perl wide
2331 characters are not used. By default, most returned strings are encoded
2332 in UTF-8. For these, Encode::decode_utf8() may be used to convert to a
2333 sequence of logical Perl characters. Note that some settings of the
2334 PERL_UNICODE environment variable may be incompatible with ExifTool's
2335 character handling.
2336 More specific details are given below about how character coding is
2338 handled for EXIF, IPTC, XMP, PNG, ID3, PDF, Photoshop, QuickTime, AIFF,
2339 MIE and Vorbis information:
2340 EXIF
2342 Most textual information in EXIF is stored in ASCII format (called
2343 "string" in the ExifTool tag name documentation). By default ExifTool
2344 does not convert these strings. However, it is not uncommon for
2345 applications to write UTF-8 or other encodings where ASCII is expected.
2346 To deal with these, ExifTool allows the internal EXIF string encoding
2347 to be specified with "CharsetEXIF", which causes EXIF string values to
2348 be converted from the specified character set when reading, and stored
2349 with this character set when writing. (The MWG recommends using UTF-8
2350 encoding for EXIF strings, and in keeping with this the MWG module sets
2351 the default internal EXIF string encoding to UTF-8, but note that this
2352 will have no effect unless the external encoding is also set to
2353 something other than the default of UTF-8.)
2354 A few EXIF tags (UserComment, GPSProcessingMethod and
2356 GPSAreaInformation) support a designated internal text encoding, with
2357 values stored as ASCII, Unicode (UCS-2) or JIS. When reading these
2358 tags, ExifTool converts Unicode and JIS to the external character set
2359 specified by the "Charset" option, or to UTF-8 by default. ASCII text
2360 is not converted. When writing, text is stored as ASCII unless the
2361 string contains special characters, in which case it is converted from
2362 the external character set (UTF-8 by default), and stored as Unicode.
2363 ExifTool writes Unicode in native EXIF byte ordering by default, but
2364 the byte order may be specified by setting the ExifUnicodeByteOrder tag
2365 (see the Extra Tags documentation).
2366 The EXIF "XP" tags (XPTitle, XPComment, etc) are always stored as
2368 little-endian Unicode (UCS-2), and are read and written using the
2369 specified character set.
2370 IPTC
2372 The value of the IPTC:CodedCharacterSet tag determines how the internal
2373 IPTC string values are interpreted. If CodedCharacterSet exists and
2374 has a value of 'UTF8' (or 'ESC % G') then string values are assumed to
2375 be stored as UTF-8, otherwise Windows Latin1 (cp1252, 'Latin') coding
2376 is assumed by default, but this can be changed with the "CharsetIPTC"
2377 option. When reading, these strings are converted to the character set
2378 specified by the "Charset" option. When writing, the inverse
2379 conversions are performed. No conversion is done if the internal
2380 (IPTC) and external (ExifTool) character sets are the same. Note that
2381 ISO 2022 character set shifting is not supported. Instead, a warning
2382 is issued and the string is not converted if an ISO 2022 shift code is
2383 encountered. See <http://www.iptc.org/IIM/> for the official IPTC
2384 specification.
2385 ExifTool may be used to convert IPTC values to a different internal
2387 encoding. To do this, all IPTC tags must be rewritten along with the
2388 desired value of CodedCharacterSet. For example, the following command
2389 changes the internal IPTC encoding to UTF-8 (from Windows Latin1 unless
2390 CodedCharacterSet was already 'UTF8'):
2391 exiftool -tagsfromfile @ -iptc:all -codedcharacterset=utf8 a.jpg
2393 or from Windows Latin2 (cp1250) to UTF-8:
2395 exiftool -tagsfromfile @ -iptc:all -codedcharacterset=utf8 \
2397 -charset iptc=latin2 a.jpg
2398 and this command changes it back from UTF-8 to Windows Latin1 (cp1252):
2400 exiftool -tagsfromfile @ -iptc:all -codedcharacterset= a.jpg
2402 or to Windows Latin2:
2404 exiftool -tagsfromfile @ -iptc:all -codedcharacterset= \
2406 -charset iptc=latin2 a.jpg
2407 Unless CodedCharacterSet is 'UTF8', applications have no reliable way
2409 to determine the IPTC character encoding. For this reason, it is
2410 recommended that CodedCharacterSet be set to 'UTF8' when creating new
2411 IPTC.
2412 (Note: Here, "IPTC" Refers to the older IPTC IIM format. The more
2414 recent IPTC Core and Extension specifications actually use the XMP
2415 format.)
2416 XMP
2418 ExifTool reads XMP encoded as UTF-8, UTF-16 or UTF-32, and converts
2419 them all to UTF-8 internally. Also, all XML character entity
2420 references and numeric character references are converted. When
2421 writing, ExifTool always encodes XMP as UTF-8, converting the following
2422 5 characters to XML character references: & < > ' ". By default no
2423 further conversion is performed, however if the "Charset" option is
2424 other than 'UTF8' then text is converted to/from the specified
2425 character set when reading/writing.
2426 PNG
2428 PNG TextualData tags are stored as tEXt, zTXt and iTXt chunks in PNG
2429 images. The tEXt and zTXt chunks use ISO 8859-1 encoding, while iTXt
2430 uses UTF-8. When reading, ExifTool converts all PNG textual data to
2431 the character set specified by the "Charset" option. When writing,
2432 ExifTool generates a tEXt chunk (or zTXt with the "Compress" option) if
2433 the text doesn't contain special characters or if Latin encoding is
2434 specified; otherwise an iTXt chunk is used and the text is converted
2435 from the specified character set and stored as UTF-8.
2436 JPEG Comment
2438 The encoding for the JPEG Comment (COM segment) is not specified, so
2439 ExifTool reads/writes this text without conversion.
2440 ID3
2442 The ID3v1 specification officially supports only ISO 8859-1 encoding (a
2443 subset of Windows Latin1), although some applications may incorrectly
2444 use other character sets. By default ExifTool converts ID3v1 text from
2445 Latin to the character set specified by the "Charset" option. However,
2446 the internal ID3v1 charset may be specified with the "CharsetID3"
2447 option. The encoding for ID3v2 information is stored in the file, so
2448 ExifTool converts ID3v2 text from this encoding to the character set
2449 specified by the "Charset" option. ExifTool does not currently write
2450 ID3 information.
2451 PDF
2453 PDF text strings are stored in either PDFDocEncoding (similar to
2454 Windows Latin1) or Unicode (UCS-2). When reading, ExifTool converts to
2455 the character set specified by the "Charset" option. When writing,
2456 ExifTool encodes input text from the specified character set as Unicode
2457 only if the string contains special characters, otherwise
2458 PDFDocEncoding is used.
2459 Photoshop
2461 Some Photoshop resource names are stored as Pascal strings with unknown
2462 encoding. By default, ExifTool assumes MacRoman encoding and converts
2463 this to UTF-8, but the internal and external character sets may be
2464 specified with the "CharsetPhotoshop" and "Charset" options
2465 respectively.
2466 QuickTime
2468 QuickTime text strings may be stored in a variety of poorly document
2469 formats. ExifTool does its best to decode these according to the
2470 "Charset" option setting. For some QuickTime strings, ExifTool assumes
2471 a default encoding of MacRoman, but this may be changed with the
2472 "CharsetQuickTime" option.
2473 AIFF
2475 AIFF strings are assumed to be stored in MacRoman, and are converted
2476 according to the "Charset" option when reading.
2477 RIFF
2479 The internal encoding of RIFF strings (eg. in AVI and WAV files) is
2480 assumed to be Latin unless otherwise specified by the RIFF CSET chunk
2481 or the "CharsetRIFF" option.
2482 MIE
2484 MIE strings are stored as either UTF-8 or ISO 8859-1. When reading,
2485 UTF-8 strings are converted according to the "Charset" option, and ISO
2486 8859-1 strings are never converted. When writing, input strings are
2487 converted from the specified character set to UTF-8. The resulting
2488 strings are stored as UTF-8 if they contain multi-byte UTF-8 character
2489 sequences, otherwise they are stored as ISO 8859-1.
2490 Vorbis
2492 Vorbis comments are stored as UTF-8, and are converted to the character
2493 set specified by the "Charset" option.
2494
2496 Copyright 2003-2022, Phil Harvey
2497 This library is free software; you can redistribute it and/or modify it
2499 under the same terms as Perl itself.
2500
2502 Many people have helped in the development of ExifTool through their
2503 bug reports, comments and suggestions, and/or additions to the code.
2504 See the ACKNOWLEDGEMENTS in the individual Image::ExifTool modules and
2505 in html/index.html of the Image::ExifTool distribution package for a
2506 list of people who have contributed to this project.
2507
2509 exiftool(1), Image::ExifTool::TagNames(3pm),
2510 Image::ExifTool::Shortcuts(3pm), Image::ExifTool::Shift(3pm),
2511 Image::Info(3pm), Image::MetaData::JPEG(3pm)
2512perl v5.36.0 2022-07-22 Image::ExifTool(3)