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