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