Changeset 34921 for main/trunk/greenstone2/perllib/cpan/Image/ExifTool.pod
- Timestamp:
- 2021-02-26T19:39:51+13:00 (3 years ago)
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
main/trunk/greenstone2/perllib/cpan/Image/ExifTool.pod
r24107 r34921 4 4 # Description: Read and write meta information 5 5 # 6 # URL: http ://owl.phy.queensu.ca/~phil/exiftool/6 # URL: https://exiftool.org/ 7 7 # 8 # Legal: Copyright (c) 2003-20 10, Phil Harvey (phil at owl.phy.queensu.ca)8 # Legal: Copyright (c) 2003-2021, Phil Harvey (philharvey66 at gmail.com) 9 9 # This library is free software; you can redistribute it and/or 10 10 # modify it under the same terms as Perl itself. … … 54 54 =head1 DESCRIPTION 55 55 56 ExifTool provides an extensible set of perl modules to read and write meta 57 information in a wide variety of files, including the maker note information 58 of many digital cameras by various manufacturers such as Canon, Casio,59 FujiFilm, GE, HP, JVC/Victor, Kodak, Leaf, Minolta/Konica-Minolta, Nikon,60 Olympus/Epson, Panasonic/Leica, Pentax/Asahi, Reconyx, Ricoh, Samsung, 61 S anyo, Sigma/Foveon and Sony.56 Reads and writes meta information in a wide variety of files, including the 57 maker notes of many digital cameras by various manufacturers such as Canon, 58 Casio, DJI, FLIR, FujiFilm, GE, GoPro, HP, JVC/Victor, Kodak, Leaf, 59 Minolta/Konica-Minolta, Nikon, Nintendo, Olympus/Epson, Panasonic/Leica, 60 Pentax/Asahi, Phase One, Reconyx, Ricoh, Samsung, Sanyo, Sigma/Foveon and 61 Sony. 62 62 63 63 Below is a list of file types and meta information formats currently … … 66 66 File Types 67 67 ------------+-------------+-------------+-------------+------------ 68 3FR r | DVB r | M4A/V r | PBM r/w | RWL r/w 69 3G2 r | DYLIB r | MEF r/w | PDF r/w | RWZ r 70 3GP r | EIP r | MIE r/w/c | PEF r/w | RM r 71 ACR r | EPS r/w | MIFF r | PFA r | SO r 72 AFM r | ERF r/w | MKA r | PFB r | SR2 r/w 73 AI r/w | EXE r | MKS r | PFM r | SRF r 74 AIFF r | EXIF r/w/c | MKV r | PGF r | SRW r/w 75 APE r | F4A/V r | MNG r/w | PGM r/w | SVG r 76 ARW r/w | FLA r | MOS r/w | PICT r | SWF r 77 ASF r | FLAC r | MOV r | PMP r | THM r/w 78 AVI r | FLV r | MP3 r | PNG r/w | TIFF r/w 79 BMP r | FPX r | MP4 r | PPM r/w | TTC r 80 BTF r | GIF r/w | MPC r | PPT r | TTF r 81 COS r | GZ r | MPG r | PPTX r | VRD r/w/c 82 CR2 r/w | HDP r/w | MPO r/w | PS r/w | VSD r 83 CRW r/w | HTML r | MQV r | PSB r/w | WAV r 84 CS1 r/w | ICC r/w/c | MRW r/w | PSD r/w | WDP r/w 85 DCM r | IIQ r/w | MXF r | PSP r | WEBP r 86 DCP r/w | IND r/w | NEF r/w | QTIF r | WEBM r 87 DCR r | ITC r | NRW r/w | RA r | WMA r 88 DFONT r | JNG r/w | NUMBERS r | RAF r/w | WMV r 89 DIVX r | JP2 r/w | ODP r | RAM r | X3F r/w 90 DJVU r | JPEG r/w | ODS r | RAR r | XCF r 91 DLL r | K25 r | ODT r | RAW r/w | XLS r 92 DNG r/w | KDC r | OGG r | RIFF r | XLSX r 93 DOC r | KEY r | ORF r/w | RSRC r | XMP r/w/c 94 DOCX r | LNK r | OTF r | RTF r | ZIP r 95 DV r | M2TS r | PAGES r | RW2 r/w | 68 360 r/w | DPX r | ITC r | ODP r | RIFF r 69 3FR r | DR4 r/w/c | J2C r | ODS r | RSRC r 70 3G2 r/w | DSS r | JNG r/w | ODT r | RTF r 71 3GP r/w | DV r | JP2 r/w | OFR r | RW2 r/w 72 A r | DVB r/w | JPEG r/w | OGG r | RWL r/w 73 AA r | DVR-MS r | JSON r | OGV r | RWZ r 74 AAE r | DYLIB r | K25 r | ONP r | RM r 75 AAX r/w | EIP r | KDC r | OPUS r | SEQ r 76 ACR r | EPS r/w | KEY r | ORF r/w | SKETCH r 77 AFM r | EPUB r | LA r | OTF r | SO r 78 AI r/w | ERF r/w | LFP r | PAC r | SR2 r/w 79 AIFF r | EXE r | LNK r | PAGES r | SRF r 80 APE r | EXIF r/w/c | LRV r/w | PBM r/w | SRW r/w 81 ARQ r/w | EXR r | M2TS r | PCD r | SVG r 82 ARW r/w | EXV r/w/c | M4A/V r/w | PCX r | SWF r 83 ASF r | F4A/V r/w | MACOS r | PDB r | THM r/w 84 AVI r | FFF r/w | MAX r | PDF r/w | TIFF r/w 85 AVIF r/w | FITS r | MEF r/w | PEF r/w | TORRENT r 86 AZW r | FLA r | MIE r/w/c | PFA r | TTC r 87 BMP r | FLAC r | MIFF r | PFB r | TTF r 88 BPG r | FLIF r/w | MKA r | PFM r | TXT r 89 BTF r | FLV r | MKS r | PGF r | VCF r 90 CHM r | FPF r | MKV r | PGM r/w | VRD r/w/c 91 COS r | FPX r | MNG r/w | PLIST r | VSD r 92 CR2 r/w | GIF r/w | MOBI r | PICT r | WAV r 93 CR3 r/w | GPR r/w | MODD r | PMP r | WDP r/w 94 CRM r/w | GZ r | MOI r | PNG r/w | WEBP r 95 CRW r/w | HDP r/w | MOS r/w | PPM r/w | WEBM r 96 CS1 r/w | HDR r | MOV r/w | PPT r | WMA r 97 CSV r | HEIC r/w | MP3 r | PPTX r | WMV r 98 CZI r | HEIF r/w | MP4 r/w | PS r/w | WTV r 99 DCM r | HTML r | MPC r | PSB r/w | WV r 100 DCP r/w | ICC r/w/c | MPG r | PSD r/w | X3F r/w 101 DCR r | ICS r | MPO r/w | PSP r | XCF r 102 DFONT r | IDML r | MQV r/w | QTIF r/w | XLS r 103 DIVX r | IIQ r/w | MRW r/w | R3D r | XLSX r 104 DJVU r | IND r/w | MXF r | RA r | XMP r/w/c 105 DLL r | INSP r/w | NEF r/w | RAF r/w | ZIP r 106 DNG r/w | INSV r | NRW r/w | RAM r | 107 DOC r | INX r | NUMBERS r | RAR r | 108 DOCX r | ISO r | O r | RAW r/w | 96 109 97 110 Meta Information … … 102 115 XMP r/w/c | FotoStation r/w | MPF r 103 116 MakerNotes r/w/c | PhotoMechanic r/w | Stim r 104 Photoshop IRB r/w/c | JPEG 2000 r | APE r 105 ICC Profile r/w/c | DICOM r | Vorbis r 106 MIE r/w/c | Flash r | SPIFF r 107 JFIF r/w/c | FlashPix r | DjVu r 108 Ducky APP12 r/w/c | QuickTime r | M2TS r 109 PDF r/w/c | Matroska r | PE/COFF r 110 PNG r/w/c | GeoTIFF r | AVCHD r 111 Canon VRD r/w/c | PrintIM r | ZIP r 112 Nikon Capture r/w/c | ID3 r | (and more) 117 Photoshop IRB r/w/c | JPEG 2000 r | DPX r 118 ICC Profile r/w/c | DICOM r | APE r 119 MIE r/w/c | Flash r | Vorbis r 120 JFIF r/w/c | FlashPix r | SPIFF r 121 Ducky APP12 r/w/c | QuickTime r | DjVu r 122 PDF r/w/c | Matroska r | M2TS r 123 PNG r/w/c | MXF r | PE/COFF r 124 Canon VRD r/w/c | PrintIM r | AVCHD r 125 Nikon Capture r/w/c | FLAC r | ZIP r 126 GeoTIFF r/w/c | ID3 r | (and more) 113 127 114 128 =head1 CONFIGURATION … … 121 135 By default ExifTool looks for a configuration file named ".ExifTool_config" 122 136 first in your home directory, then in the directory of the application 123 script, but a different file may be specified by setting the ExifTool 124 C<configFile> variable before using Image::ExifTool. For example: 137 script, but a different directory may be specified by setting the 138 EXIFTOOL_HOME environment variable, or a different file may be specified by 139 setting the ExifTool C<configFile> variable before using Image::ExifTool. 140 For example: 125 141 126 142 BEGIN { $Image::ExifTool::configFile = '/Users/phil/myconfig.cfg' } 127 143 use Image::ExifTool; 128 144 129 or the configuration feature may be disabled by setting C<configFile> to an 130 empty string:145 The configuration feature may also be disabled by setting C<configFile> to 146 an empty string: 131 147 132 148 BEGIN { $Image::ExifTool::configFile = '' } … … 146 162 147 163 None of these methods should ever die or issue warnings to STDERR if called 148 with the proper arguments (with the exception of L</SetNewValue> which 149 returns an error string when called in list context, or sends the error to 150 STDERR otherwise). Error and warning messages that occur during processing 151 are stored in the values of the Error and Warning tags, and are accessible 152 via the L</GetValue> method. 164 with the proper arguments (with the exception of L</SetNewValue> which may 165 send an error message to STDERR, but only when called in scalar context). 166 Error and warning messages that occur during processing are stored in the 167 values of the Error and Warning tags, and are accessible via the 168 L</GetValue> method to retrieve a single Error or Warning message, or 169 L</GetInfo> to retrieve any number of them. 170 171 The ExifTool methods are not thread safe. 153 172 154 173 =head2 new … … 160 179 Note that ExifTool uses AUTOLOAD to load non-member methods, so any class 161 180 using Image::ExifTool as a base class must define an AUTOLOAD which calls 162 Image::ExifTool::DoAutoLoad(). ie)181 Image::ExifTool::DoAutoLoad(). eg) 163 182 164 183 sub AUTOLOAD … … 209 228 =item ExifTool ref 210 229 211 L</ImageInfo> may be called with an ExifTool object if desired. The212 advantage of using the object-oriented form is that the options may be set 213 before calling L</ImageInfo>, and the object may be used afterward to access 214 memberfunctions. Must be the first argument if used.230 L</ImageInfo> may be called with an ExifTool object if desired. Advantages 231 of using the object-oriented form are that options may be set before calling 232 L</ImageInfo>, and the object may be used afterward to access member 233 functions. Must be the first argument if used. 215 234 216 235 =item SCALAR … … 222 241 223 242 Tag names are case-insensitive and may be prefixed by optional group names 224 separated by colons. A group name may begin with a family number ( ie.243 separated by colons. A group name may begin with a family number (eg. 225 244 '1IPTC:Keywords'), to restrict matches to a specific family. In the tag 226 245 name, a '?' matches any single character and a '*' matches zero or more … … 228 247 Wildcards may not be used in group names, with the exception that a group 229 248 name of '*' may be used to extract all available instances of a tag 230 regardless of the L</Duplicates> setting ( ie. '*:WhiteBalance'). Multiple231 groups may be specified ( ie. 'EXIF:Time:*' extracts all EXIF Time tags). And232 finally, a leading '-' indicates a tag to be excluded ( ie. '-IFD1:*'), or a249 regardless of the L</Duplicates> setting (eg. '*:WhiteBalance'). Multiple 250 groups may be specified (eg. 'EXIF:Time:*' extracts all EXIF Time tags). And 251 finally, a leading '-' indicates a tag to be excluded (eg. '-IFD1:*'), or a 233 252 trailing '#' causes the ValueConv value to be returned for this tag. 234 253 … … 237 256 are removed, the case may be changed, and an instance number may be added. 238 257 For this reason it is best to use either the keys of the returned hash or 239 the elements of the tag arraywhen accessing the tag values.258 the elements of the returned tag list when accessing the tag values. 240 259 241 260 See L<Image::ExifTool::TagNames|Image::ExifTool::TagNames> for a complete … … 246 265 A reference to an open image file. If you use this method (or a SCALAR 247 266 reference) to access information in an image, the FileName and Directory 248 tags will not be returned. (Also, the FileSize, FileModifyDate and 249 FilePermissions tags will not be returned unless it is a plain file.) Image 250 processing begins at the current file position, and on return the file 251 position is unspecified. May be either a standard filehandle, or a 252 reference to a L<File::RandomAccess|File::RandomAccess> object. Note that 253 the file remains open and must be closed by the caller after L</ImageInfo> 254 returns. 255 256 [Advanced: To allow a non-rewindable stream (ie. a network socket) to be 267 tags will not be returned. (Also, a number of the File System tags will not 268 be returned unless it is a plain file.) Image processing begins at the 269 current file position, and on return the file position is unspecified. May 270 be either a standard filehandle, or a reference to a 271 L<File::RandomAccess|File::RandomAccess> object. Note that the file remains 272 open and must be closed by the caller after L</ImageInfo> returns. 273 274 [Advanced: To allow a non-rewindable stream (eg. a network socket) to be 257 275 re-read after processing with ExifTool, first wrap the file reference in a 258 276 L<File::RandomAccess|File::RandomAccess> object, then pass this object to … … 276 294 (With L</Duplicates> enabled, there may be more entries in the returned list 277 295 of tag keys, and with other L</Sort> settings the entries may not be in the 278 same order as requested.) 296 same order as requested.) If a requested tag doesn't exist, a tag key is 297 still generated, but the tag value is undefined. 279 298 280 299 =item HASH ref 281 300 282 Reference to a hash containing the options settings. See L</Options> 283 documentation below for a list of available options. Options specified 284 as arguments to L</ImageInfo> take precedence over L</Options> settings. 301 Reference to a hash containing the options settings valid for this call 302 only. See L</Options> documentation below for a list of available options. 303 Options specified as arguments to L</ImageInfo> take precedence over 304 L</Options> settings. 285 305 286 306 =back … … 288 308 =item Return Values: 289 309 290 L</ImageInfo> returns a reference to a hash of tag 291 keys are identifiers , which are similar to the tag names but may havean292 embedded instance number if multiple tags with the same name were extracted310 L</ImageInfo> returns a reference to a hash of tag-key/value pairs. The tag 311 keys are identifiers -- essentially case-sensitive tag names with an 312 appended instance number if multiple tags with the same name were extracted 293 313 from the image. Many of the ExifTool functions require a tag key as an 294 argument. Use L</GetTagName [static]> to get the tag name for a given tag314 argument. Use L</GetTagName [static]> to get the tag name for a given tag 295 315 key. Note that the case of the tag names may not be the same as requested. 296 316 Here is a simple example to print out the information returned by … … 305 325 to indicate a list. Also, a hash reference may be returned if the L</Struct> 306 326 option is used. Lists of values are joined by commas into a single 307 string only if the PrintConv option is enabled and the List option is308 disabled (which are the defaults). Note that binary values are not309 necessarily extracted unless specifically requested or the Binary option is310 set. If not extracted the value is a reference to a string of the form 311 "Binary data ##### bytes".327 string only if the PrintConv option is enabled and the ListJoin option is 328 enabled (which are the defaults). Note that binary values are not 329 necessarily extracted unless specifically requested, or the Binary option is 330 enabled and the tag is not specifically excluded. If not extracted the 331 value is a reference to a string of the form "Binary data ##### bytes". 312 332 313 333 The code below gives an example of how to handle these return values, as … … 341 361 ExifTool returns all values as byte strings of encoded characters. Perl 342 362 wide characters are not used. See L</CHARACTER ENCODINGS> for details about 343 the encodings. 344 345 As well as tags representing information extracted from the image, 346 the following tags generated by ExifTool may be returned: 363 the encodings. By default, most returned values are encoded in UTF-8. For 364 these, Encode::decode_utf8() may be used to convert to a sequence of logical 365 Perl characters. 366 367 As well as tags representing information extracted from the image, the 368 following L<Extra tags|Image::ExifTool::TagNames/Extra Tags> generated by 369 ExifTool may be returned: 347 370 348 371 ExifToolVersion - The ExifTool version number. … … 360 383 options for an ExifTool object. Options set this way are in effect for 361 384 all function calls but may be overridden by options passed as arguments 362 to some functions. 363 364 The initial default options are obtained from values in the365 %Image::ExifTool::UserDefined::Options hash if it exists. See the366 .ExifTool_config file in the full ExifTool distribution for details.385 to some functions. Option names are not case sensitive. 386 387 The default option values may be changed by defining a 388 %Image::ExifTool::UserDefined::Options hash. See the ExifTool_config file 389 in the full ExifTool distribution for examples. 367 390 368 391 # exclude the 'OwnerName' tag from returned information … … 387 410 $isVerbose = $exifTool->Options('Verbose'); 388 411 389 =over 4 390 391 =item Inputs: 392 393 0) ExifTool object reference. 394 395 1) Option parameter name. 396 397 2) [optional] Option parameter value (may be undef to clear option). 398 399 3-N) [optional] Additional parameter/value pairs. 412 # set a user parameter 413 $exifTool->Options(UserParam => 'MyParam=some value'); 414 415 =over 4 416 417 =item Inputs: 418 419 0) ExifTool object reference 420 421 1) Option parameter name (case-insensitive) 422 423 2) [optional] Option parameter value (may be undef to clear option) 424 425 3-N) [optional] Additional parameter/value pairs 400 426 401 427 =item Option Parameters: 402 428 429 Note that these API options may also be used in the exiftool application via 430 the command-line B<-api> option. 431 403 432 =over 4 404 433 … … 406 435 407 436 Flag to extract the value data for all binary tags. Tag values representing 408 large binary data blocks ( ie. ThumbnailImage) are not necessarily extracted437 large binary data blocks (eg. ThumbnailImage) are not necessarily extracted 409 438 unless this option is set or the tag is specifically requested by name. 410 Default is 0.439 Default is undef. 411 440 412 441 =item ByteOrder … … 417 446 then the maker note byte order is used (if they are being copied), otherwise 418 447 big-endian ('MM') order is assumed. This can also be set via the 419 ExifByteOrder tag, but the ByteOrder option takes precedence if both are 420 set.448 L<ExifByteOrder tag|Image::ExifTool::TagNames/Extra Tags>, but the ByteOrder 449 option takes precedence if both are set. 421 450 422 451 =item Charset 423 452 424 Character set for encoding character strings passed to/from ExifTool with425 code points above U+007F. Default is UTF8. Valid values are listed below,426 case is not significant:453 Character set for encoding character tag values passed to/from ExifTool with 454 code points above U+007F. Default is 'UTF8'. Valid values are listed 455 below, case is not significant: 427 456 428 457 Value Alias(es) Description … … 439 468 Vietnam cp1258 Windows Vietnamese 440 469 Thai cp874 Windows Thai 470 DOSLatinUS cp437 DOS Latin US 471 DOSLatin1 cp850 DOS Latin1 472 DOSCyrillic cp866 DOS Cyrillic 441 473 MacRoman cp10000, Roman Macintosh Roman 442 474 MacLatin2 cp10029 Macintosh Latin2 (Central Europe) … … 450 482 Note that this option affects some types of information when reading/writing 451 483 the file and other types when getting/setting tag values, so it must be 452 defined for both types of access. 484 defined for both types of access. See the L</CHARACTER ENCODINGS> section 485 for more information about the handling of special characters. 486 487 =item CharsetEXIF 488 489 Internal encoding to use for stored EXIF "ASCII" string values. May also be 490 set to undef to pass through EXIF "ASCII" values without recoding. Set to 491 "UTF8" to conform with the MWG recommendation. Default is undef. 492 493 =item CharsetFileName 494 495 External character set used for file names passed to ExifTool functions. 496 When set in Windows, this triggers use of Windows wide-character i/o library 497 routines (requires Win32API::File). Default is undef. May also be set to 498 an empty string to avoid "encoding not specified" warnings on Windows. 453 499 454 500 =item CharsetID3 455 501 456 Characterencoding to assume for ID3v1 strings. By the specification ID3v1502 Internal encoding to assume for ID3v1 strings. By the specification ID3v1 457 503 strings should be encoded in ISO 8859-1 (essentially Latin), but some 458 applications may use local encoding instead. Default is Latin.504 applications may use local encoding instead. Default is 'Latin'. 459 505 460 506 =item CharsetIPTC 461 507 462 Fallback IPTC character set to assume if IPTC information contains no463 CodedCharacterSet tag. Possible values are the same as the L</Charset>464 option. Default is Latin.508 Fallback internal IPTC character set to assume if IPTC information contains 509 no CodedCharacterSet tag. Possible values are the same as the L</Charset> 510 option. Default is 'Latin'. 465 511 466 512 Note that this option affects some types of information when reading/writing … … 470 516 =item CharsetPhotoshop 471 517 472 Character encoding to assume for Photoshop IRB resource names. Default is 473 Latin. 518 Internal encoding to assume for Photoshop IRB resource names. Default is 519 'Latin'. 520 521 =item CharsetQuickTime 522 523 Internal encoding to assume for QuickTime strings stored with an unspecified 524 encoding. Default is 'MacRoman'. 525 526 =item CharsetRIFF 527 528 Internal encoding to assume for strings in RIFF metadata (eg. AVI and WAV 529 files). The default value of 0 assumes "Latin" encoding unless otherwise 530 specified by the RIFF CSET chunk. Set to undef to pass through strings 531 without recoding. Default is 0. 474 532 475 533 =item Compact 476 534 477 Flag to write compact output. Default is 0. The XMP specification suggests 478 that the data be padded with blanks to allow in-place editing. With this 479 flag set the 2kB of padding is not written. Note that this only effects 480 embedded XMP since padding is never written for stand-alone XMP files. 535 Comma-delimited list of settings for writing compact XMP. Below is a list 536 of available settings. Note that 'NoPadding' effects only embedded XMP 537 since padding is never written for stand-alone XMP files. Also note that 538 'OneDesc' is not recommended when writing XMP larger than 64 kB to a JPG 539 file because it interferes with ExifTool's technique of splitting off large 540 rdf:Description elements into the extended XMP. Case is not significant for 541 any of these options. Aliases are given in brackets. Default is undef. 542 543 NoPadding - Avoid 2 kB of recommended padding at end of XMP (NoPad) 544 NoIndent - No spaces to indent lines (NoSpace, NoSpaces) 545 NoNewline - Avoid unnecessary newlines (NoNewlines) 546 Shorthand - Use XMP Shorthand format 547 OneDesc - Combine properties into a single rdf:Description (OneDescr) 548 AllSpace - Equivalent to 'NoPadding,NoIndent,NoNewline' 549 AllFormat - Equivalent to 'Shorthand,OneDesc' 550 All - Equivalent to 'AllSpace,AllFormat' 481 551 482 552 =item Composite 483 553 484 Flag to calculate Composite tags automatically. Default is 1.554 Flag to generate Composite tags when extracting information. Default is 1. 485 555 486 556 =item Compress 487 557 488 558 Flag to write new values in compressed format if possible. Has no effect 489 unless Compress::Zlib is installed. Default is 0.559 unless Compress::Zlib is installed. Default is undef. 490 560 491 561 =item CoordFormat … … 493 563 Format for printing GPS coordinates. This is a printf format string with 494 564 specifiers for degrees, minutes and seconds in that order, however minutes 495 and seconds may be omitted. For example, the following table gives the 496 output for the same coordinate using various formats: 565 and seconds may be omitted. If the hemisphere is known, a reference 566 direction (N, S, E or W) is appended to each printed coordinate, but adding 567 a C<+> to the first format specifier (eg. C<%+.6f>) prints a signed 568 coordinate instead. For example, the following table gives the output for 569 the same coordinate using various formats: 497 570 498 571 CoordFormat Example Output … … 509 582 510 583 Format for printing date/time values. See C<strftime> in the L<POSIX> 511 package for details about the format string. The default is similar to a 512 format of "%Y:%m:%d %H:%M:%S". If date can not be converted, value is left 513 unchanged unless the StrictDate option is set. Timezones are ignored. 584 package for details about the format string. If date can not be converted, 585 value is left unchanged unless the StrictDate option is set. Timezones are 586 ignored. The inverse conversion (ie. when calling L</SetNewValue>) is 587 performed only if POSIX::strptime or Time::Piece is installed. The default 588 setting of undef causes date/time values to remain in standard EXIF format 589 (similar to a DateFormat of "%Y:%m:%d %H:%M:%S"). 514 590 515 591 =item Duplicates … … 530 606 is either a tag name or reference to a list of tag names to exclude. The 531 607 case of tag names is not significant. This option is ignored for 532 specifically requested tags. Tags may also be excluded by prece eding their608 specifically requested tags. Tags may also be excluded by preceding their 533 609 name with a '-' in the arguments to L</ImageInfo>. 534 610 611 =item ExtendedXMP 612 613 This setting affects the reading and editing of extended XMP in JPEG images. 614 According to the XMP specification, extended XMP is only valid if it has the 615 GUID specified by the HasExtendedXMP tag, so by default ExifTool will ignore 616 other extended XMP, but this option allows full control over the extended 617 XMP to be extracted. 618 619 0 - Ignore all extended XMP 620 1 - Read extended XMP with valid GUID only (default) 621 2 - Read extended XMP with any GUID 622 <guid> - Read extended XMP with a specific GUID 623 535 624 =item ExtractEmbedded 536 625 537 Flag to extract information from embedded documents in EPS and PDF files, 538 embedded MPF images in JPEG and MPO files, streaming metadata in AVCHD 539 videos, and the resource fork of Mac OS files. Default is 0. 626 Flag to extract information from embedded documents in EPS files, embedded 627 EPS information and JPEG and Jpeg2000 images in PDF files, embedded MPF 628 images in JPEG and MPO files, timed metadata in videos, and the resource 629 fork of Mac OS files. A setting of 2 also causes the H264 video stream in 630 MP4 files to be parsed until the first SEI message is decoded, or 3 to 631 parse the entire stream. Default is undef. 540 632 541 633 =item FastScan 542 634 543 Flag to increase speed of extracting information from JPEG images. With 544 this option set to 1, ExifTool will not scan to the end of a JPEG image to 545 check for an AFCP, CanonVRD, FotoStation, PhotoMechanic, MIE or PreviewImage 546 trailer. This also stops the parsing after the first comment in GIF images, 547 and at the audio/video data with RIFF-format files (AVI, WAV, etc), so any 548 trailing metadata (ie. XMP written by some utilities) may be missed. When 635 Flag to increase speed when reading files by avoiding extraction of some 636 types of metadata. With this option set to 1, ExifTool will not scan to the 637 end of a JPEG image to check for an AFCP, CanonVRD, FotoStation, 638 PhotoMechanic, MIE or PreviewImage trailer. This also stops the parsing 639 after the first comment in GIF images, and at the audio/video data of 640 RIFF-format files (AVI, WAV, etc), so any trailing metadata (eg. XMP written 641 by some utilities) may be missed. Also disables input buffering for some 642 types of files to reduce memory usage when reading from a non-seekable 643 stream, and bypasses CRC validation for speed when writing PNG files. When 549 644 combined with the ScanForXMP option, prevents scanning for XMP in recognized 550 645 file types. With a value of 2, ExifTool will also avoid extracting any EXIF 551 MakerNote information. Default is 0. 646 MakerNote information, and will stop parsing at the IDAT chunk of PNG 647 images. (By the PNG specification, metadata is allowed after IDAT, but 648 ExifTool always writes it before because some utilities will ignore it 649 otherwise.) When set to 3 or higher, only pseudo system tags and FileType 650 are generated. For 3, the file header is read to provide an educated guess 651 at FileType. For 4, the file is not read at all and FileType is determined 652 based on the file's extension. For 5, generation of Composite tags is also 653 disabled (like setting L</Composite> to 0). Default is undef. 654 655 =item Filter 656 657 Perl expression used to filter values for all tags. The expression acts on 658 the value of the Perl default variable ($_), and changes the value of this 659 variable as required. The current ExifTool object may be accessed through 660 $self. The value is not changed if $_ is set to undef. List items are 661 filtered individually. Applies to all returned values unless PrintConv 662 option is disabled. 663 664 =item FilterW 665 666 Perl expression used to filter PrintConv values when writing. The 667 expression acts on the value of the Perl default variable ($_), and changes 668 the value of this variable as required. The current ExifTool object may be 669 accessed through $self. The tag is not written if $_ is set to undef. 552 670 553 671 =item FixBase … … 563 681 =item GeoMaxIntSecs 564 682 565 Maximum interpolation time in seconds for geotagging. Geotagging fails if 566 the Geotime value lies between two fixes in the same track which are 567 separated by a number of seconds greater than this. Default is 1800. 683 Maximum interpolation time in seconds for geotagging. Geotagging is treated 684 as an extrapolation if the Geotime value lies between two fixes in the same 685 track which are separated by a number of seconds greater than this. 686 Otherwise, the coordinates are calculated as a linear interpolation between 687 the nearest fixes on either side of the Geotime value. Set to 0 to disable 688 interpolation and use the coordinates of the nearest fix instead (provided 689 it is within GeoMaxExtSecs, otherwise geotagging fails). Default is 1800. 568 690 569 691 =item GeoMaxExtSecs … … 571 693 Maximum extrapolation time in seconds for geotagging. Geotagging fails if 572 694 the Geotime value lies outside a GPS track by a number of seconds greater 573 than this. Default is 1800. 695 than this. Otherwise, for an extrapolation the coordinates of the nearest 696 fix are taken (ie. it is assumed that you weren't moving during this 697 period). Default is 1800. 574 698 575 699 =item GeoMaxHDOP … … 587 711 Minimum number of satellites for geotagging. GPS fixes are ignored if the 588 712 number of acquired satellites is less than this. Default is undef. 713 714 =item GeoSpeedRef 715 716 Reference units for writing GPSSpeed when geotagging: 717 718 'K', 'k' or 'km/h' - km/h 719 'M', 'm' or 'mph' - mph 720 <anything else> - knots (default undef) 721 722 =item GlobalTimeShift 723 724 Time shift to apply to all extracted date/time PrintConv values. Does not 725 affect ValueConv values. Value is a date/time shift string (see 726 L<Image::ExifTool::Shift(3pm)|Image::ExifTool::Shift.pl>), with a leading 727 '-' for negative shifts. Default is undef. 589 728 590 729 =item Group# … … 597 736 group names. 598 737 738 =item HexTagIDs 739 740 Return hexadecimal instead of decimal for the family 7 group names of tags 741 with numerical ID's. 742 599 743 =item HtmlDump 600 744 … … 605 749 =item HtmlDumpBase 606 750 607 Specifies base for HTML dump offsets. If not defined, the EXIF/TIFF base 608 offset isused. Set to 0 for absolute offsets. Default is undef.751 Base for HTML dump offsets. If not defined, the EXIF/TIFF base offset is 752 used. Set to 0 for absolute offsets. Default is undef. 609 753 610 754 =item IgnoreMinorErrors … … 615 759 minor warnings the behaviour of ExifTool may be changed to allow some 616 760 questionable operations to proceed (such as extracting thumbnail and preview 617 images even if they don't have a recognizable header). Minor 618 errors/warnings are denoted by '[minor]' at the start of the message. 761 images even if they don't have a recognizable header). Minor errors and 762 warnings are denoted by "[minor]" at the start of the message, or "[Minor]" 763 (with a capital "M") for warnings that affect processing when ignored. 619 764 620 765 =item Lang 621 766 622 767 Localized language for exiftool tag descriptions, etc. Available languages 623 are given by the Image::ExifTool::Lang module names ( ie. 'fr'). If the624 specified language isn't available, the option is not changed. May be set 625 to undef to select the built-in default language. Default is 'en'.768 are given by the Image::ExifTool::Lang module names (eg. 'fr', 'zh_cn'). If 769 the specified language isn't available, the option is not changed. May be 770 set to undef to select the built-in default language. Default is 'en'. 626 771 627 772 =item LargeFileSupport 628 773 629 774 Flag to indicate that 64-bit file offsets are supported on this system. 630 Default is 0. 631 632 =item List 633 634 Flag to extract lists of PrintConv values into arrays instead of joining 635 them into a string of values. The L</ListSep> option specifies the 636 separator used when combining values. Default is 0. 637 638 =item ListSep 639 640 Separator string used to join lists of PrintConv values when L</List> option 641 is not set. Default is ', '. 775 Default is undef. 776 777 =item ListItem 778 779 Return only a specific item from list-type values. A value of 0 returns the 780 first item in the list, 1 return the second item, etc. Negative indices may 781 also be used, with -1 representing the last item in the list. Applies only 782 to the top-level list of nested lists. Default is undef to return all items 783 in the list. 784 785 =item ListJoin 786 787 Separator used to join the PrintConv value of multi-item List-type tags into 788 a single string. If not defined, multi-item lists are returned as a list 789 reference. Does not affect ValueConv values. Default is ', '. 642 790 643 791 =item ListSplit 644 792 645 793 Regular expression used to split values of list-type tags into individual 646 items when writing. ( ie. use ',\\s*' to split a comma-separated list.)647 Default is undef.794 items when writing. (eg. use ',\\s*' to split a comma-separated list.) 795 Split when writing either PrintConv or ValueConv values. Default is undef. 648 796 649 797 =item MakerNotes … … 655 803 are: 656 804 657 0 - Do not extract writable subdirectories ( default)805 0 - Do not extract writable subdirectories (same as default of undef) 658 806 1 - Extract and rebuild maker notes into self-contained block 659 807 2 - Extract without rebuilding maker notes 660 808 809 =item MDItemTags 810 811 Flag to extract the OS X metadata item tags (see the "mdls" man page and 812 L<Image::ExifTool::TagNames/MacOS MDItem Tags> for more information). 813 661 814 =item MissingTagValue 662 815 663 Value for missing tags in expressions evaluated by L</SetNewValuesFromFile>. 664 If not set, a minor error is issued for missing values, or the value is set 665 to '' if L</IgnoreMinorErrors> is set. Default is undef. 816 Value for missing tags in tag name expressions (or tags where the advanced 817 formatting expression returns undef). If not set, a minor error is issued 818 for missing values, or the value is set to '' if L</IgnoreMinorErrors> is 819 set. Default is undef. 820 821 =item NoMultiExif 822 823 Raise error when attempting to write multi-segment EXIF in a JPEG image. 824 Default is undef. 825 826 =item NoPDFList 827 828 Flag to avoid splitting PDF list-type tag values into separate items. 829 Default is undef. 666 830 667 831 =item Password 668 832 669 Password for processing password-protected PDF documents. Ignored if a833 Password for reading/writing password-protected PDF documents. Ignored if a 670 834 password is not required. Character encoding of the password is determined 671 835 by the value of the Charset option at processing time. Default is undef. … … 676 840 print conversion for writing. Default is 1. 677 841 842 =item QuickTimeHandler 843 844 Flag set to add an 'mdir' Handler to a newly created Meta box when adding 845 QuickTime ItemList tags. Adobe Bridge does not add this Handler, but it is 846 commonly found in samples from other software, and it has been reported that 847 Apple QuickTime Player and Photos.apps will ignore ItemList tags if this is 848 missing. Default is 1. 849 850 =item QuickTimeUTC 851 852 Flag set to assume that QuickTime date/time values are stored as UTC, 853 causing conversion to local time when they are extracted and from local time 854 when written. According to the QuickTime specification date/time values 855 should be UTC, but many digital cameras store local time instead (presumably 856 because they don't know the time zone), so the default is to not convert 857 these times (except for Canon CR3 files, which always use UTC times). This 858 option also disables the autodetection of incorrect time-zero offsets in 859 QuickTime date/time values, and enforces a time zero of 1904 as per the 860 QuickTime specification. 861 862 =item RequestAll 863 864 Flag to request all tags to be extracted. This causes some tags to be 865 generated which normally would not be unless specifically requested (by 866 passing the tag name to L</ImageInfo> or L</ExtractInfo>). May be set to 2 867 or 3 to enable generation of some additional tags as mentioned in the tag 868 name documentation. Default is undef. 869 870 =item RequestTags 871 872 List of additional tag and/or group names to request in the next call to 873 L</ExtractInfo>. This option is useful only for tags/groups which aren't 874 extracted unless specifically requested. Value may be a list reference, a 875 delimited string of names (any delimiter is allowed), or undef to clear the 876 current RequestTags list. Groups are requested by adding a colon after the 877 name (eg. "MacOS:"). Names are converted to lower case as they are added to 878 the list. Default is undef. 879 880 =item SaveFormat 881 882 Flag to save EXIF/TIFF format type as the family 6 group name when 883 extracting information. Without this option set, the family 6 group names 884 are not generated. Default is undef. See the L</GetGroup> option for more 885 details. 886 887 =item SavePath 888 889 Flag to save the metadata path as the family 5 group name when extracting 890 information. Without this option set, the family 5 group names are not 891 generated. Default is undef. See the L</GetGroup> option for more details. 892 678 893 =item ScanForXMP 679 894 680 Flag forscan all files (even unrecognized formats) for XMP information895 Flag to scan all files (even unrecognized formats) for XMP information 681 896 unless XMP was already found in the file. When combined with the FastScan 682 option, only unrecognized file types are scanned for XMP. Default is 0.897 option, only unrecognized file types are scanned for XMP. Default is undef. 683 898 684 899 =item Sort … … 687 902 688 903 Input - Sort in same order as input tag arguments (default) 689 Alpha - Sort alphabetically690 904 File - Sort in order that tags were found in the file 905 Tag - Sort alphabetically by tag name 906 Descr - Sort by tag description (for current Lang setting) 691 907 Group# - Sort by tag group, where # is zero or more family 692 908 numbers separated by colons. If # is not specified, … … 694 910 of group families. 695 911 912 =item Sort2 913 914 Secondary sort order used for tags within each group when Sort is 'Group': 915 916 File - Sort in order tags were found in the file (default) 917 Tag - Sort alphabetically by tag name 918 Descr - Sort by tag description (for current Lang setting) 919 696 920 =item StrictDate 697 921 … … 699 923 the DateFormat option is used. Default is undef. 700 924 925 undef - Same as 0 for reading/writing, or 1 for copying 926 0 - Return date/time value unchanged if it can't be converted 927 1 - Return undef if date/time value can't be converted 928 929 When set to 1 while writing a PrintConv date/time value with the DateFormat 930 option set, the value is written only if POSIX::strptime or Time::Piece is 931 available and can successfully convert the value. 932 933 For PNG CreationTime, a setting of 1 has the additional effect of causing 934 the date/time to be reformatted according to PNG 1.2 recommendation 935 (RFC-1123) when writing, and a warning to be issued for any non-standard 936 value when reading (but note that Windows may not recognize PNG date/time 937 values in standard format). 938 701 939 =item Struct 702 940 703 941 Flag to return XMP structures as hash references instead of flattening into 704 individual tags. If not defined (the default), tags are flattened when 705 reading (with L<ExtractInfo>), and structured when copying (with 706 L</SetNewValuesFromFile>). Has no effect when writing since both flattened 707 and structured tags may always be written. Possible values are: 708 709 undef - Read flattened tags, copy structured tags (default) 710 0 - Read and copy flattened tags 711 1 - Read and copy structured tags 942 individual tags. Has no effect when writing since both flattened and 943 structured tags may always be written. Possible values are: 944 945 undef - (default) Same as 0 for reading, 2 for copying 946 0 - Read/copy flattened tags 947 1 - Read/copy structured tags 948 2 - Read/copy both flattened and structured tags, but flag 949 flattened tags as 'unsafe' for copying 950 951 =item SystemTags 952 953 Flag to extract the following additional File System tags: FileAttributes, 954 FileDeviceNumber, FileInodeNumber, FileHardLinks, FileUserID, FileGroupID, 955 FileDeviceID, FileBlockSize and FileBlockCount. 712 956 713 957 =item TextOut … … 715 959 Output file reference for Verbose and HtmlDump options. Default is 716 960 \*STDOUT. 961 962 =item TimeZone 963 964 Time zone for local date/time values. May be set to any valid TZ string. 965 Uses the system time zone if not specified. Default is undef. (Requires 966 POSIX::tzset, which may not be available in Windows. A work-around in 967 Windows is to C<set TZ=E<lt>zoneE<gt>> before running ExifTool.) 717 968 718 969 =item Unknown … … 721 972 extracted from EXIF (or other tagged-format) directories. If set to 2, 722 973 unknown tags are also extracted from binary data blocks. Default is 0. 974 975 =item UserParam 976 977 Special option to set/get user-defined parameters. Useful to allow external 978 input into tag name expressions and ValueConv logic. Valid UserParam values 979 are: 980 981 PARAM - Get parameter 982 PARAM= - Clear parameter 983 PARAM^= - Set parameter to empty string 984 PARAM=VALUE - Set parameter 985 <hash ref> - Set entire UserParam hash lookup 986 undef - Clear all user parameters 987 988 Where I<PARAM> is the user-defined parameter name (case insensitive). 989 990 User-defined parameters may be accessed in tag name expressions by prefixing 991 the parameter name with a dollar sign just like normal tags, or via the API 992 by calling C<Options('UserParam','PARAM')>. Appending a hash tag (C<#>) to 993 the parameter name also causes the parameter to be extracted as a normal tag 994 (in the UserParam group). If called without additional arguments, 995 C<Options('UserParam')> returns a reference to the hash of all user 996 parameters (with lower-case names). 997 998 =item Validate 999 1000 Flag to perform extra validation metadata checks when reading, causing extra 1001 warnings to be generated if problems are found. Default is undef. 723 1002 724 1003 =item Verbose … … 732 1011 on tag values and JPEG segment data respectively. 733 1012 1013 =item WriteMode 1014 1015 Set tag write/create mode. Value is a string of one or more characters from 1016 list below. Default is 'wcg'. 1017 1018 w - Write existing tags 1019 c - Create new tags 1020 g - create new Groups as necessary 1021 1022 The level of the group differs for different types of metadata. For XMP or 1023 IPTC this is the full XMP/IPTC block (the family 0 group), but for EXIF this 1024 is the individual IFD (the family 1 group). The 'w' and 'c' modes are 1025 tested only when L</SetNewValue> is called, but the 'g' mode is also tested 1026 in L</WriteInfo>. 1027 1028 =item XAttrTags 1029 1030 Flag to extract the OS X extended attribute tags (see the "xattr" man page 1031 and L<Image::ExifTool::TagNames/MacOS XAttr Tags> for more information). 1032 1033 =item XMPAutoConv 1034 1035 Flag to enable automatic conversion for unknown XMP tags with values that 1036 look like rational numbers or dates. Default is 1. 1037 734 1038 =back 735 1039 … … 775 1079 L</ExtractInfo>: 776 1080 777 Binary, Charset, CharsetID3, CharsetIPTC, Composite, ExtractEmbedded, 778 FastScan, FixBase, HtmlDump, HtmlDumpBase, IgnoreMinorErrors, Lang, 779 LargeFileSupport, MakerNotes, ScanForXMP, Struct, TextOut, Unknown and 780 Verbose. 1081 Binary, Charset, CharsetEXIF, CharsetFileName, CharsetID3, CharsetIPTC, 1082 CharsetPhotoshop, CharsetQuickTime, CharsetRIFF, Composite, ExtendedXMP, 1083 ExtractEmbedded, FastScan, FixBase, HtmlDump, HtmlDumpBase, 1084 IgnoreMinorErrors, Lang, LargeFileSupport, MakerNotes, MDItemTags, 1085 NoPDFList, Password, QuickTimeUTC (enforced 1904 time zero), RequestAll, 1086 RequestTags, SaveFormat, SavePath, ScanForXMP, Struct, TextOut, Unknown, 1087 Verbose, XAttrTags and XMPAutoConv. 781 1088 782 1089 =item Return Value: … … 793 1100 L</ImageInfo>. 794 1101 795 # get image width and h ieght only1102 # get image width and height only 796 1103 $info = $exifTool->GetInfo('ImageWidth', 'ImageHeight'); 1104 1105 # get all Error and Warning messages 1106 $info = $exifTool->GetInfo('Error', 'Warning'); 797 1107 798 1108 # get information for all tags in list (list updated with tags found) … … 809 1119 image can not be specified. Options in effect are: 810 1120 811 Charset, CoordFormat, DateFormat, Duplicates, Escape, Exclude, Group#, Lang, 812 List, ListSep, PrintConv, Sort (if a tag list reference is given) and 1121 Charset, CoordFormat, DateFormat, Duplicates, Escape, Exclude, Filter, 1122 Group#, GlobalTimeShift, Lang, ListItem, ListJoin, PrintConv, Sort (if a tag 1123 list reference is given) and StrictDate. 1124 1125 =item Return Value: 1126 1127 Reference to information hash, the same as with L</ImageInfo>. 1128 1129 =back 1130 1131 The following options are effective in the call to L</GetInfo>: 1132 1133 Charset, CoordFormat, DateFormat, Duplicates, Escape, Exclude, Filter, 1134 Group#, GlobalTimeShift, Lang, ListItem, ListJoin, PrintConv, QuickTimeUTC 1135 (conversion to local time), Sort (if a tag list reference is given) and 813 1136 StrictDate. 814 815 =item Return Value:816 817 Reference to information hash, the same as with L</ImageInfo>.818 819 =back820 1137 821 1138 =head2 WriteInfo … … 828 1145 additional files without the need to call L</SetNewValue> again. 829 1146 1147 ExifTool queues all new values that are assigned via calls to 1148 L</SetNewValue>, then applies them to any number of files through one or 1149 more calls to L</WriteInfo>. These queued values may be accessed through 1150 L</GetNewValue>, and are completely separate from metadata extracted from 1151 files via L</ExtractInfo> or L</ImageInfo> and accessed through L</GetInfo> 1152 or L</GetValue>. 1153 1154 To be clear, it is NOT necessary to call L</ExtractInfo> or L</ImageInfo> 1155 before L</WriteInfo>. L</WriteInfo> changes only metadata specified by 1156 previous calls to L</SetNewValue>. 1157 830 1158 # add information to a source file, writing output to new file 831 1159 $exifTool->WriteInfo($srcfile, $dstfile); … … 844 1172 845 1173 1) Source file name, file reference, scalar reference, or undef to create a 846 file from scratch 1174 file from scratch. A reference to a 1175 L<File::RandomAccess|File::RandomAccess> object is also allowed as a source, 1176 but in this case the destination is not optional. 847 1177 848 1178 2) [optional] Destination file name, file reference, scalar reference, or 849 undef to overwrite the original file 850 851 3) [optional] Destination file type 1179 undef to overwrite the original file. May be '-' to write to stdout. 1180 1181 3) [optional] Destination file type. Ignored if a source is defined. 852 1182 853 1183 =item Return Value: … … 867 1197 868 1198 The source file name may be undefined to create a file from scratch 869 (currently only XMP, MIE, ICC, VRD and EXIF files can be created in this way870 -- see L</CanCreate> for details). If undefined, the destination file type871 is required unless the type can be determined from the destination file872 name.1199 (currently only XMP, MIE, ICC, VRD, DR4, EXV and EXIF files can be created 1200 in this way -- see L</CanCreate> for details). If undefined, the 1201 destination file type is required unless the type can be determined from the 1202 extension of the destination file name. 873 1203 874 1204 If a destination file name is given, the specified file must not exist 875 because an existing destination file will not be overwritten. The 876 destination file name may be undefined to overwrite the original file (make 877 sure you have backups!). In this case, if a source file name is provided, a 878 temporary file is created and renamed to replace the source file if no 879 errors occurred while writing. Otherwise, if a source file reference or 880 scalar reference is used, the image is first written to memory then copied 881 back to replace the original if there were no errors. 882 883 The destination file type is only used if the source file is undefined. 1205 because an existing destination file will not be overwritten. Any new 1206 values for FileName, Directory or HardLink are ignored when a destination 1207 file name is specified. 1208 1209 The destination file name may be undefined to overwrite the original file 1210 (make sure you have backups!). In this case, if a source file name is 1211 provided, a temporary file is created and renamed to replace the source file 1212 if no errors occurred while writing. Otherwise, if a source file reference 1213 or scalar reference is used, the image is first written to memory then 1214 copied back to replace the original if there were no errors. 884 1215 885 1216 On Mac OS systems, the file resource fork is preserved if this routine is … … 890 1221 The following ExifTool options are effective in the call to L</WriteInfo>: 891 1222 892 ByteOrder, Charset, CharsetID3, CharsetIPTC, Compact, Compress, FixBase, 893 IgnoreMinorErrors and Verbose. 894 895 =head2 CombineInfo 896 897 Combine information from more than one information hash into a single hash. 898 899 $info = $exifTool->CombineInfo($info1, $info2, $info3); 1223 ByteOrder, Charset, CharsetEXIF, CharsetFileName, CharsetIPTC, Compact, 1224 Compress, FixBase, IgnoreMinorErrors, Password, QuickTimeHandler, Verbose 1225 and WriteMode. 1226 1227 =head2 GetTagList 1228 1229 Get a sorted list of tags from the specified information hash or tag list. 1230 1231 @tags = $exifTool->GetTagList($info, 'Group0'); 900 1232 901 1233 =over 4 … … 905 1237 0) ExifTool object reference 906 1238 907 1-N) Information hash references 908 909 =back 910 911 If the Duplicates option is disabled and duplicate tags exist, the order of 912 the hashes is significant. In this case, the value used is the first value 913 found as the hashes are scanned in order of input. The Duplicates option 914 is the only option that is in effect for this function. 915 916 =head2 GetTagList 917 918 Get a sorted list of tags from the specified information hash or tag list. 919 920 @tags = $exifTool->GetTagList($info, 'Group0'); 921 922 =over 4 923 924 =item Inputs: 925 926 0) ExifTool object reference, 927 928 1) [optional] Information hash reference or tag list reference, 929 930 2) [optional] Sort order ('File', 'Input', 'Alpha' or 'Group#'). 1239 1) [optional] Information hash reference or tag list reference 1240 1241 2) [optional] Sort order ('Input', 'File', 'Tag', 'Descr' or 'Group#') 1242 1243 3) [optional] Secondary sort order ('File', 'Tag' or 'Descr') 931 1244 932 1245 If the information hash or tag list reference is not provided, then the list … … 956 1269 0) ExifTool object reference 957 1270 958 1) [optional] Sort order ('File', 'Input', 'Alpha' or 'Group#') 1271 1) [optional] Sort order ('Input', 'File', 'Tag', 'Descr' or 'Group#') 1272 1273 2) [optional] Secondary sort order ('File', 'Tag' or 'Descr') 959 1274 960 1275 If sort order is not specified, the sort order from the ExifTool options is … … 994 1309 Get the value of a specified tag. The returned value is either the 995 1310 human-readable (PrintConv) value, the converted machine-readable (ValueConv) 996 value, or the original raw (Raw) value. If the value type is not specified, 997 the PrintConv value is returned if the PrintConv option is set, otherwise 998 the ValueConv value is returned. The PrintConv values are same as the 999 values returned by L</ImageInfo> and L</GetInfo> in the tag/value hash 1000 unless the PrintConv option is disabled. 1311 value, the original raw (Raw) value, or the original rational (Rational) 1312 value for rational formats. If the value type is not specified, the 1313 PrintConv value is returned if the PrintConv option is set, otherwise the 1314 ValueConv value is returned. The PrintConv values are same as the values 1315 returned by L</ImageInfo> and L</GetInfo> in the tag/value hash unless the 1316 PrintConv option is disabled. 1001 1317 1002 1318 Tags which represent lists of multiple values (as may happen with 'Keywords' 1003 1319 for example) are handled specially. In scalar context, the returned 1004 1320 PrintConv value for these tags is either a string of values or a list 1005 reference (depending on the List option setting), and the ValueConv value is1006 always a list reference. But in list context, L</GetValue> always returns1007 the list itself.1321 reference (depending on the ListJoin option setting), and the ValueConv 1322 value is always a list reference. But in list context, L</GetValue> always 1323 returns the list itself. 1008 1324 1009 1325 Note that L</GetValue> requires a case-sensitive tag key as an argument. To … … 1031 1347 my @keywords = $exifTool->GetValue('Keywords', 'ValueConv'); 1032 1348 1033 The following options are in effect when <L/GetValue> is called: 1034 1035 Charset, CoordFormat, DateFormat, Escape, Lang, List, ListSep, PrintConv and 1036 StrictDate. 1349 The following options are in effect when L</GetValue> is called: 1350 1351 Charset, CoordFormat, DateFormat, Escape, Filter, GlobalTimeShift, Lang, 1352 ListItem, ListJoin, PrintConv, QuickTimeUTC (conversion to local time), 1353 StrictDate and TimeZone. 1037 1354 1038 1355 =over 4 … … 1042 1359 0) ExifTool object reference 1043 1360 1044 1) Tag key 1045 1046 2) [optional] Value type, 'PrintConv', 'ValueConv', 'Both' or 'Raw' 1361 1) Tag key, or case-sensitive tag name with optional group prefix(es) 1362 1363 2) [optional] Value type: 'PrintConv', 'ValueConv', 'Both', 'Raw' or 1364 'Rational' 1047 1365 1048 1366 The default value type is 'PrintConv' if the PrintConv option is set, 1049 1367 otherwise the default is 'ValueConv'. A value type of 'Both' returns both 1050 ValueConv and PrintConv values as a list. 1368 ValueConv and PrintConv values as a list. 'Rational' returns the raw 1369 rational value as a string fraction for rational types, or undef for other 1370 types. 1051 1371 1052 1372 =item Return Values: 1053 1373 1054 The value of the specified tag. If the tag represents a list of values and 1055 the List option is disabled then PrintConv returns a string of values, 1056 otherwise a reference to the list is returned in scalar context. The list 1057 itself is returned in list context. Values may also be scalar references to 1058 binary data, or hash references if the Struct option is set. 1374 The value of the specified tag. If the tag represents a list of multiple 1375 values and the ListJoin option is enabled then PrintConv returns a string of 1376 values, otherwise a reference to the list is returned in scalar context. The 1377 list itself is returned in list context. (Unless 'Both' values are 1378 requested, in which case two list references are returned, regardless of 1379 context.) Values may also be scalar references to binary data, or hash 1380 references if the L</Struct> option is set. 1059 1381 1060 1382 Note: It is possible for L</GetValue> to return an undefined ValueConv or 1061 1383 PrintConv value (or an empty list in list context) even if the tag exists, 1062 since it is possible for these conversions to yield undefined values. 1384 since it is possible for these conversions to yield undefined values. And 1385 the Rational value will be undefined for any non-rational tag. The Raw 1386 value should always exist if the tag exists. 1063 1387 1064 1388 =back … … 1089 1413 $exifTool->SetNewValue('Keywords', $word, DelValue => 1); 1090 1414 1091 # set keywords (a List-type tag) with two new values1415 # set keywords (a list-type tag) with two new values 1092 1416 $exifTool->SetNewValue(Keywords => 'word1'); 1093 1417 $exifTool->SetNewValue(Keywords => 'word2'); … … 1098 1422 $exifTool->SetNewValue(Keywords => $word, AddValue => 1); 1099 1423 1424 # conditionally add a tag if it didn't exist before, 1425 # or replace it if it had a specified value ("old value") 1426 $exifTool->SetNewValue(Description => '', DelValue => 1); 1427 $exifTool->SetNewValue(Description => 'old value', DelValue => 1); 1428 $exifTool->SetNewValue(Description => 'new value'); 1429 1100 1430 # set a tag in a specific group 1101 1431 $exifTool->SetNewValue(Headline => $val, Group => 'XMP'); 1102 1432 $exifTool->SetNewValue('XMP:Headline' => $val); # (equivalent) 1103 1433 1104 # shift original date/time back by 1 hour1105 $exifTool->SetNewValue(DateTimeOriginal => ' 1:00', Shift => -1);1434 # shift original date/time back by 2.5 hours 1435 $exifTool->SetNewValue(DateTimeOriginal => '2:30', Shift => -1); 1106 1436 1107 1437 # write a tag only if it had a specific value … … 1128 1458 $exifTool->SetNewValue('XMP:Flash'=>'{mode=on,fired=true,return=not}'); 1129 1459 1130 (See L<http ://owl.phy.queensu.ca/~phil/exiftool/struct.html#Serialize> for1131 a description of thestructure serialization technique.)1460 (See L<https://exiftool.org/struct.html#Serialize> for a description of the 1461 structure serialization technique.) 1132 1462 1133 1463 =over 4 … … 1137 1467 0) ExifTool object reference 1138 1468 1139 1) [optional] Tag key or tag name, or undef to clear all new values. A tag 1140 name of '*' can be used when deleting tags to delete all tags, or all tags 1141 in a specified group. The tag name may be prefixed by group name, separated 1142 by a colon (ie. 'EXIF:Artist'), which is equivalent to using a Group option 1143 argument. Also, a '#' may be appended to the tag name (ie. 1144 'EXIF:Orientation#'), with the same effect as setting Type to 'ValueConv'. 1469 1) [optional] Tag key or tag name, or undef to clear all new values. The 1470 tag name may be prefixed by one or more family 0, 1 or 2 group names with 1471 optional leading family numbers, separated by colons (eg. 'EXIF:Artist', 1472 'XMP:Time:*'), which is equivalent to using a Group option argument. Also, 1473 a '#' may be appended to the tag name (eg. 'EXIF:Orientation#'), with the 1474 same effect as setting Type to 'ValueConv'. Wildcards ('*' and '?') may be 1475 used in the tag name to assign multiple tags simultaneously. A tag name of 1476 '*' is special when deleting information, and will delete an entire group 1477 even if some individual tags in the group are not writable, but only if a 1478 single family 0 or 1 group is specified (otherwise the tags are deleted 1479 individually). Use L</GetDeleteGroups> to get a list of deletable group 1480 names, and see L<Image::ExifTool::TagNames|Image::ExifTool::TagNames> for a 1481 complete list of tag names. 1145 1482 1146 1483 2) [optional] New value for tag. Undefined to delete tag from file. May be … … 1148 1485 reference for a structure. Integer values may be specified as a hexadecimal 1149 1486 string (with a leading '0x'), and simple rational values may be specified in 1150 fractional form ( ie. '4/10'). Structure tags may be specified either as a1487 fractional form (eg. '4/10'). Structure tags may be specified either as a 1151 1488 hash reference or a serialized string (see the last two examples above). 1152 1489 … … 1159 1496 =item AddValue 1160 1497 1161 Specifies that the value be added to an existing list rather than replacing 1162 the list. Valid values are 0 or 1. Default is 0. 1498 Specifies that the value be added to an existing list in a file rather than 1499 overwriting the existing values. Valid settings are 0 (overwrite any 1500 existing tag value), 1 (add to an existing list and warn for non-list tags) 1501 or 2 (add to existing list and overwrite non-list tags). Default is 0. 1163 1502 1164 1503 =item DelValue 1165 1504 1166 Delete the existing tag if it has the specified value. Valid values are 1167 0 or 1. Default is 0. 1505 Delete existing tag from a file if it has the specified value. For 1506 list-type tags this deletes a specified item from the list. For non-list 1507 tags this may be used to conditionally replace a tag by providing a new 1508 value in a separate call to L<SetNewValue> (see examples above). For 1509 structured tags, the entire structure is deleted/replaced only if all of the 1510 specified fields match the existing structure. Option values are 0 or 1. 1511 Default is 0. 1168 1512 1169 1513 =item EditGroup 1170 1514 1171 1515 Create tags in existing groups only. Don't create new group. Valid values 1172 are 0 and 1. Default is 0. 1516 are 0 and 1. Effectively removes the 'g' from the ExifTool WriteMode option 1517 for this tag only. Default is 0. 1173 1518 1174 1519 =item EditOnly 1175 1520 1176 1521 Edit tag only if it already exists. Don't create new tag. Valid values are 1177 0 and 1. Default is 0. 1522 0 and 1. Effectively removes the 'c' from the ExifTool WriteMode option for 1523 this tag only. Default is 0. 1178 1524 1179 1525 =item Group 1180 1526 1181 Specifies group name where tag should be written. If not specified, tag is 1182 written to highest priority group as specified by L</SetNewGroups>. Any 1183 family 0 or 1 group name may be used. Case is not significant. 1527 Specifies group name where tag should be written. This option is superseded 1528 by any group specified in the tag name. If not specified, tag is written to 1529 highest priority group as specified by L</SetNewGroups>. May be one or more 1530 family 0, 1 or 2 groups with optional leading family number, separated by 1531 colons. Case is not significant. 1532 1533 =item NoFlat 1534 1535 Treat flattened tags as 'unsafe'. 1184 1536 1185 1537 =item NoShortcut … … 1197 1549 names indicating 'unsafe' and 'protected' tags. Default is 0. 1198 1550 1551 =item ProtectSaved 1552 1553 Avoid setting new values which were saved after the Nth call to 1554 L</SaveNewValues>. Has no effect on unsaved values, or values saved before 1555 Nth call. Option value is N. Default is undef. 1556 1199 1557 =item Replace 1200 1558 1201 1559 Flag to replace the previous new values for this tag (ie. replace the values 1202 1560 set in previous calls to L</SetNewValue>). This option is most commonly 1203 used to replace previously-set new values for List-type tags. Valid values1204 are 0 (set new value normally -- adds to new values for List-type tags), 11205 (reset previous new values for this tag and replace with the specified new1206 value) or 2 (reset previous new values only).1561 used to replace previously-set new values for list-type tags. Valid values 1562 are 0 (set new value normally -- adds to new values for list-type tags), 1 1563 (reset any previous new values before setting new value) or 2 (reset 1564 previous new values only; new value argument is ignored). Default is 0. 1207 1565 1208 1566 =item Shift 1209 1567 1210 Shift the tag by the specified value. Currently only date/time tags can be 1211 shifted. Undefined for no shift, 1 for a positive shift, or -1 for a 1212 negative shift. If 0, the shift is applied only if the tag is shiftable, 1213 and the shift is positive if AddValue is set, or negative if DelValue is 1214 set. Default is undef. See 1215 L<Image::ExifTool::Shift.pl|Image::ExifTool::Shift.pl> for more information. 1568 Shift the tag by the specified value. Currently only date/time tags and 1569 tags with numerical values may be shifted. Undefined for no shift, 1 for a 1570 positive shift, or -1 for a negative shift. A value of 0 causes a positive 1571 shift to be applied if the tag is shiftable and AddValue is set, or a 1572 negative shift for date/time tags only if DelValue is set. Default is undef. 1573 See L<Image::ExifTool::Shift(3pm)|Image::ExifTool::Shift.pl> for more 1574 information. 1216 1575 1217 1576 =item Type … … 1226 1585 1227 1586 In scalar context, returns the number of tags set and error messages are 1228 printed to STDERR. In list context, returns the number of tags set and the1229 error string .1587 printed to STDERR. In list context, returns the number of tags set, and the 1588 error string (which is undefined if there was no error). 1230 1589 1231 1590 =item Notes: 1232 1591 1233 When deleting groups of tags, the Replace option may be used as in the last 1234 example above to exclude specific groups from a mass delete. However, this 1235 technique may not be used to exclude individual tags. Instead, use 1236 L</SetNewValuesFromFile> to recover the values of individual tags after 1237 deleting a group. 1592 When deleting groups of tags, the Replace option may be used to exclude 1593 specific groups from a mass delete. However, this technique may not be used 1594 to exclude individual tags from a group delete (unless a family 2 group was 1595 specified in the delete). Instead, use L</SetNewValuesFromFile> to recover 1596 the values of individual tags after deleting a group. 1597 1598 When deleting all tags from a JPEG image, the APP14 "Adobe" information is 1599 not deleted by default because doing so may affect the appearance of the 1600 image. However, this information may be deleted by specifying it 1601 explicitly, either by group (with 'Adobe:*') or as a block (with 'Adobe'). 1238 1602 1239 1603 =back … … 1241 1605 The following ExifTool options are effective in the call to L</SetNewValue>: 1242 1606 1243 Charset, Escape, IgnoreMinorErrors, Lang, ListSep, ListSplit, PrintConv and 1244 Verbose. 1607 Charset, DateFormat, Escape, IgnoreMinorErrors, Lang, ListJoin, ListSplit, 1608 PrintConv, QuickTimeUTC, StrictDate, TimeZone, Verbose and WriteMode. 1609 1610 =head2 GetNewValue 1611 1612 Get the new Raw value for a tag. This is the value set by L</SetNewValue> 1613 this is queued to be written to file. List-type tags may return multiple 1614 values in list context. 1615 1616 $rawVal = $exifTool->GetNewValue($tag); 1617 1618 @rawVals = $exifTool->GetNewValue($tag); 1619 1620 =over 4 1621 1622 =item Inputs: 1623 1624 0) ExifTool object reference 1625 1626 1) Tag name (case sensitive, may be prefixed by family 0, 1 or 7 group 1627 names, separated by colons) 1628 1629 =item Return Values: 1630 1631 List of new Raw tag values, or first value in list when called in scalar 1632 context. The list may be empty either if the tag isn't being written, or if 1633 it is being deleted (ie. if L</SetNewValue> was called without a value). 1634 1635 =back 1245 1636 1246 1637 =head2 SetNewValuesFromFile … … 1261 1652 1262 1653 # set new value from a different tag in specific group 1263 $exifTool->SetNewValuesFromFile($fp, ' IPTC:Keywords>XMP-dc:Subject');1654 $exifTool->SetNewValuesFromFile($fp, 'XMP-dc:Subject<IPTC:Keywords'); 1264 1655 1265 1656 # add all IPTC keywords to XMP subject list 1266 $exifTool->SetNewValuesFromFile($fp, ' IPTC:Keywords+>XMP-dc:Subject');1657 $exifTool->SetNewValuesFromFile($fp, 'XMP-dc:Subject+<IPTC:Keywords'); 1267 1658 1268 1659 # set new value from an expression involving other tags … … 1275 1666 1276 1667 # copy all EXIF information, preserving the original IFD 1277 # (without '>*.*' tags would be copied to the preferred EXIF IFD) 1278 $exifTool->SetNewValuesFromFile($file, 'EXIF:*>*:*'); 1668 # (without '*.*<' tags would be copied to the preferred EXIF IFD) 1669 $exifTool->SetNewValuesFromFile($file, '*:*<EXIF:*'); 1670 1671 # copy all tags with names starting with "gps" (note: this is 1672 # different than "gps:*" because it will also copy XMP GPS tags) 1673 $exifTool->SetNewValuesFromFile($file, 'gps*'); 1674 1675 # set FileName from Model, translating questionable characters 1676 $exifTool->SetNewValuesFromFile($file, 1677 'filename<${model; tr(/\\\\?*:|"><)(_) }.jpg'); 1279 1678 1280 1679 =over 4 … … 1288 1687 2-N) [optional] List of tag names to set or options hash references. All 1289 1688 writable tags are set if none are specified. The tag names are not case 1290 sensitive, and may be prefixed by an optional family 0 or 1 group name, 1291 separated by a colon (ie. 'exif:iso'). A leading '-' indicates tags to be 1292 excluded (ie. '-comment'), or a trailing '#' causes the ValueConv value to 1293 be copied (same as setting the Type option to 'ValueConv' for this tag 1294 only). An asterisk ('*') may be used for the tag name, and is useful when a 1295 group is specified to set all tags from a group (ie. 'XMP:*'). A special 1296 feature allows tag names of the form 'SRCTAG>DSTTAG' (or 1297 'DSTTAGE<lt>SRCTAG') to be specified to copy information to a tag with a 1298 different name or a specified group. Both 'SRCTAG' and 'DSTTAG' may use '*' 1299 and/or be prefixed by a group name (ie. 'modifyDate>fileModifyDate' or 1300 '*>xmp:*'). Copied tags may also be added or deleted from a list with 1301 arguments of the form 'SRCTAG+>DSTTAG' or 'SRCTAG->DSTTAG'. Tags are 1302 evaluated in order, so exclusions apply only to tags included earlier in the 1303 list. An extension of this feature allows the tag value to be set from an 1304 expression containing tag names with leading '$' symbols (ie. 1305 'CommentE<lt>the file is $filename'). Braces '{}' may be used around the tag 1306 name to separate it from subsequent text, and a '$$' is used to to represent 1307 a '$' symbol. (The behaviour for missing tags in expressions is defined by 1308 the L</MissingTagValue> option.) Multiple options hash references may be 1309 passed to set different options for different tags. Options apply to 1310 subsequent tags in the argument list. 1689 sensitive, and may be prefixed by one or more family 0, 1, 2 or 7 group 1690 names with optional leading family numbers, separated by colons (eg. 1691 'exif:iso'). A leading '-' indicates tags to be excluded (eg. '-comment'), 1692 or a trailing '#' causes the ValueConv value to be copied (same as setting 1693 the Type option to 'ValueConv' for this tag only). Wildcards ('*' and '?') 1694 may be used in the tag name. A tag name of '*' is commonly used when a 1695 group is specified to copy all tags in the group (eg. 'XMP:*'). A special 1696 feature allows tag names of the form 'DSTTAGE<lt>SRCTAG' (or 1697 'SRCTAGE<gt>DSTTAG') to be specified to copy information to a tag with a 1698 different name or a specified group. Both 'SRCTAG' and 'DSTTAG' may contain 1699 wildcards and/or be prefixed by a group name (eg. 1700 'fileModifyDateE<lt>modifyDate' or 'xmp:*E<lt>*'), and/or suffixed by a '#' 1701 to disable print conversion. Copied tags may also be added or deleted from 1702 a list with arguments of the form 'DSTTAG+E<lt>SRCTAG' or 1703 'DSTTAG-E<lt>SRCTAG'. Tags are evaluated in order, so exclusions apply only 1704 to tags included earlier in the list. An extension of this feature allows 1705 the tag value to be set from a string containing tag names with leading '$' 1706 symbols (eg. 'CommentE<lt>the file is $filename'). Braces '{}' may be used 1707 around the tag name to separate it from subsequent text, and a '$$' is used 1708 to to represent a '$' symbol. The behaviour for missing tags in expressions 1709 is defined by the L</MissingTagValue> option. The tag value may be modified 1710 via changes to the default input variable ($_) in a Perl expression placed 1711 inside the braces and after a semicolon following the tag name (see the last 1712 example above). A '@' may be added after the tag name (before the 1713 semicolon) to make the expression act on individual list items instead of 1714 the concatenated string for list-type tags. Braces within the expression 1715 must be balanced. Multiple options hash references may be passed to set 1716 different options for different tags. Options apply to subsequent tags in 1717 the argument list. 1311 1718 1312 1719 By default, this routine will commute information between same-named tags in … … 1315 1722 name for extracted tags (even if '*' is used as a group name), in which case 1316 1723 the information is written to the original group, unless redirected to a 1317 different group. When '*' is used for a group name, the family 1 group of 1318 the original tag is preserved. (For example, specifying '*:*' copies all 1319 information while preserving the original family 1 groups.) 1724 different group. When '*' is used for a group name, by default the family 1 1725 group of the original tag is preserved, but a different family may be 1726 specified with a leading family number. (For example, specifying '*:*' 1727 copies all information while preserving the original family 1 groups, while 1728 '0*:*' preserves the family 0 group.) 1320 1729 1321 1730 =item SetNewValuesFromFile Options: … … 1359 1768 when copying, but the Struct option may be set to 0 to override this 1360 1769 behaviour and copy as flattened tags instead. 1361 1362 =back1363 1364 =head2 GetNewValues1365 1366 Get list of new Raw values for the specified tag. These are the values1367 that will be written to file. Only tags which support a 'List' may return1368 more than one value.1369 1370 $rawVal = $exifTool->GetNewValues($tag);1371 1372 @rawVals = $exifTool->GetNewValues($tag);1373 1374 =over 41375 1376 =item Inputs:1377 1378 0) ExifTool object reference1379 1380 1) Tag name (case sensitive, may be prefixed by family 0 or 1 group name)1381 1382 =item Return Values:1383 1384 List of new Raw tag values, or first value in list when called in scalar1385 context. The list may be empty either if the tag isn't being written, or if1386 it is being deleted (ie. if L</SetNewValue> was called without a value).1387 1770 1388 1771 =back … … 1428 1811 =item Return Value: 1429 1812 1430 None. 1813 Count of the number of times this routine has been called (N) since the last 1814 time the new values were reset. 1431 1815 1432 1816 =back … … 1452 1836 =head2 SetFileModifyDate 1453 1837 1454 Set the file modification time from the new value of the FileModifyDate tag. 1838 Write the filesystem modification or creation time from the new value of the 1839 FileModifyDate or FileCreateDate tag. 1455 1840 1456 1841 $exifTool->SetNewValue(FileModifyDate => '2000:01:02 03:04:05-05:00', … … 1468 1853 2) [optional] Base time if applying shift (days before $^T) 1469 1854 1855 3) [optional] Tag to write: 'FileModifyDate' (default), or 'FileCreateDate' 1856 1470 1857 =item Return Value: 1471 1858 … … 1476 1863 1477 1864 Equivalent to, but more efficient than calling L</WriteInfo> when only the 1478 FileModifyDate tag has been set. If a timezone is not specified in the 1479 FileModifyDate value, local time is assumed. When shifting FileModifyDate, 1480 the time of the original file is used unless an optional base time is 1481 specified. 1865 FileModifyDate or FileCreateDate tag has been set. If a timezone is not 1866 specified, local time is assumed. When shifting, the time of the original 1867 file is used unless the optional base time is specified. 1868 1869 The ability to write FileCreateDate is currently restricted to Windows 1870 systems only. 1482 1871 1483 1872 =back … … 1485 1874 =head2 SetFileName 1486 1875 1487 Set the file name and directory. If not specified, the new file name is 1488 derived from the new values of the FileName and Directory tags. If the 1489 FileName tag contains a '/', then the file is renamed into a new directory. 1490 If FileName ends with '/', then it is taken as a directory name and the file 1491 is moved into the new directory. The new value for the Directory tag takes 1492 precedence over any directory specified in FileName. 1876 Set the file name and directory, or create a hard link. If not specified, 1877 the new file name is derived from the new values of the FileName and 1878 Directory tags, or from the HardLink or SymLink tag if creating a link. If 1879 the FileName tag contains a '/', then the file is renamed into a new 1880 directory. If FileName ends with '/', then it is taken as a directory name 1881 and the file is moved into the new directory. The new value for the 1882 Directory tag takes precedence over any directory specified in FileName. 1493 1883 1494 1884 $result = $exifTool->SetFileName($file); … … 1505 1895 2) [optional] New file name 1506 1896 1897 3) [optional] 'HardLink' or 'SymLink' to create a hard or symbolic link 1898 instead of renaming the file, or 'Test' to test renaming feature by printing 1899 the old and new names instead of changing anything. 1900 1507 1901 =item Return Value: 1508 1902 1509 1 if the file name or directory was changed, 0 if nothing was done, or -1 if1510 there was an error renaming the file.1903 1 on success, 0 if nothing was done, or -1 if there was an error renaming the 1904 file or creating the link. 1511 1905 1512 1906 =item Notes: 1513 1907 1514 Will not overwrite existing files. New directories are created as necessary. 1908 Will not overwrite existing files. New directories are created as necessary. 1909 If the file is successfully renamed, the new file name may be accessed via 1910 C<$$exifTool{NewName}>. 1515 1911 1516 1912 =back … … 1522 1918 first valid group of this list. This has an impact only if the group is not 1523 1919 specified when calling L</SetNewValue> and if the tag name exists in more 1524 than one group. The default order is EXIF, IPTC then XMP. Any family 0 1525 group name may be used. Case is not significant. 1920 than one group. The default order is EXIF, IPTC, XMP, MakerNotes, 1921 QuickTime, Photoshop, ICC_Profile, CanonVRD, Adobe. Any family 0 group name 1922 may be used. Case is not significant. 1526 1923 1527 1924 $exifTool->SetNewGroups('XMP','EXIF','IPTC'); … … 1566 1963 binary data block. For some tags, such as Composite tags where there is no 1567 1964 ID, an empty string is returned. In list context, also returns a language 1568 code for the tag if available and different from the default language ( ie.1965 code for the tag if available and different from the default language (eg. 1569 1966 with alternate language entries for XMP "lang-alt" tags). 1570 1967 … … 1612 2009 Get group name(s) for a specified tag. 1613 2010 1614 # return family 0 group name ( ie. 'EXIF');2011 # return family 0 group name (eg. 'EXIF'); 1615 2012 $group = $exifTool->GetGroup($tag, 0); 1616 2013 1617 # return all groups ( ie. qw{EXIF IFD0 Author Main})2014 # return all groups (eg. qw{EXIF IFD0 Author Main}) 1618 2015 @groups = $exifTool->GetGroup($tag); 1619 2016 1620 # return groups as a string ( ie. 'Main:IFD0:Author')2017 # return groups as a string (eg. 'Main:IFD0:Author') 1621 2018 $group = $exifTool->GetGroup($tag, ':3:1:2'); 1622 2019 1623 # return groups as a simplified string ( ie. 'IFD0:Author')2020 # return groups as a simplified string (eg. 'IFD0:Author') 1624 2021 $group = $exifTool->GetGroup($tag, '3:1:2'); 1625 2022 … … 1647 2044 The group family numbers are currently available: 1648 2045 1649 0) Information Type (ie. EXIF, XMP, IPTC) 1650 1) Specific Location (ie. IFD0, XMP-dc) 1651 2) Category (ie. Author, Time) 1652 3) Document Number (ie. Main, Doc1, Doc3-2) 1653 4) Instance Number (ie. Copy1, Copy2, Copy3...) 2046 0) Information Type (eg. EXIF, XMP, IPTC) 2047 1) Specific Location (eg. IFD0, XMP-dc) 2048 2) Category (eg. Author, Time) 2049 3) Document Number (eg. Main, Doc1, Doc3-2) 2050 4) Instance Number (eg. Copy1, Copy2, Copy3...) 2051 5) Metadata Path (eg. JPEG-APP1-IFD0-ExifIFD) 2052 6) EXIF/TIFF Format (eg. int8u, int32u, undef, string) 2053 7) Tag ID (eg. ID-271, ID-rights, ID-a9aut) 1654 2054 1655 2055 Families 0 and 1 are based on the file structure, and are similar except … … 1675 2075 L</ExtractEmbedded> option for extracting tags from embedded documents.) 1676 2076 Nested sub-documents (if they exist) are indicated by numbers separated with 1677 dashes in the group name, to an arbitrary depth. ( ie. 'Doc2-3-1' is the 1st2077 dashes in the group name, to an arbitrary depth. (eg. 'Doc2-3-1' is the 1st 1678 2078 sub-sub-document of the 3rd sub-document of the 2nd embedded document of the 1679 main file.) 2079 main file.) Document numbers are also used to differentiate samples for 2080 timed metadata in videos. 1680 2081 1681 2082 Family 4 provides a method for differentiating tags when multiple tags exist 1682 2083 with the same name in the same location. The primary instance of a tag (the 1683 2084 tag extracted when the Duplicates option is disabled and no group is 1684 specified) has no family 4 group name, but additional instances have have 1685 family 4 group names of 'Copy1', 'Copy2', 'Copy3', etc. 2085 specified) has no family 4 group name, but additional instances have family 2086 4 group names of 'Copy1', 'Copy2', 'Copy3', etc. For convenience, the 2087 primary tag may also be accessed using a group name of 'Copy0'. 2088 2089 Family 5 is experimental, and gives the complete path for the metadata in 2090 the file. Generated only if the L</SavePath> option is used when 2091 extracting. 2092 2093 Family 6 is currently used only for EXIF/TIFF metadata, and gives the format 2094 type of the extracted value. Generated only if the L</SaveFormat> option is 2095 used when extracting. 2096 2097 Family 7 is used for tag ID's. The group names are the actual tag ID's, 2098 with a leading "ID-" string. Non-numerical ID's have characters other than 2099 [-_A-Za-z0-9] converted to hex. Numerical tag ID's are returned in hex if 2100 the L</HexTagIDs> option is set, otherwise decimal is used. When specifying 2101 a family 7 group name, numerical ID's may be in hex or decimal, and 2102 non-numerical ID's may or may not have characters other than [-_A-Za-z0-9] 2103 converted to hex. Note that unlike other group names, the tag ID's of 2104 family 7 group names are case sensitive (but the leading "ID-" is not). 1686 2105 1687 2106 See L</GetAllGroups [static]> for complete lists of group names. … … 1735 2154 Tag values are calculated in alphabetical order unless a tag Require's or 1736 2155 Desire's another composite tag, in which case the calculation is deferred 1737 until after the other tag is calculated. Composite tags may need to read 1738 data from the image for their value to be determined, so for these 1739 L</BuildCompositeTags> must be called while the image is available. This is 1740 only a problem if L</ImageInfo> is called with a filename (as opposed to a 1741 file reference or scalar reference) since in this case the file is closed 1742 before L</ImageInfo> returns. However if you enable the Composite option, 1743 L</BuildCompositeTags> is called from within L</ImageInfo> before the file 1744 is closed. 2156 until after the other tag is calculated. 2157 2158 Composite tags may need to read data from the image for their value to be 2159 determined, and for these L</BuildCompositeTags> must be called while the 2160 image is available. This is only a problem if L</ImageInfo> is called with 2161 a filename (as opposed to a file reference or scalar reference) since in 2162 this case the file is closed before L</ImageInfo> returns. Here the 2163 Composite option may be used so that L</BuildCompositeTags> is called from 2164 within L</ImageInfo>, before the file is closed. 1745 2165 1746 2166 =back … … 1839 2259 =item Inputs: 1840 2260 1841 0) Group family number (0- 4)2261 0) Group family number (0-7) 1842 2262 1843 2263 =item Return Values: … … 1853 2273 =item Family 0 (Information Type): 1854 2274 1855 AFCP, AIFF, APE, APP0, APP12, APP13, APP14, APP15, APP4, APP5, APP6, APP8, 1856 ASF, CanonVRD, Composite, DICOM, DNG, DV, DjVu, Ducky, EXE, EXIF, ExifTool, 1857 FLAC, File, Flash, FlashPix, Font, FotoStation, GIF, GIMP, GeoTiff, H264, 1858 HTML, ICC_Profile, ID3, IPTC, ITC, JFIF, JPEG, Jpeg2000, LNK, Leaf, M2TS, 1859 MIE, MIFF, MNG, MPC, MPEG, MPF, MXF, MakerNotes, Matroska, Meta, PDF, PICT, 1860 PNG, PSP, PhotoMechanic, Photoshop, PostScript, PrintIM, QuickTime, RAF, 1861 RIFF, RSRC, RTF, Rawzor, Real, SVG, SigmaRaw, Stim, Vorbis, XML, XMP, ZIP 2275 AFCP, AIFF, APE, APP0, APP1, APP11, APP12, APP13, APP14, APP15, APP4, APP5, 2276 APP6, APP8, ASF, Audible, CanonVRD, Composite, DICOM, DNG, DV, DjVu, Ducky, 2277 EXE, EXIF, ExifTool, FITS, FLAC, FLIR, File, Flash, FlashPix, Font, 2278 FotoStation, GIF, GIMP, GeoTiff, GoPro, H264, HTML, ICC_Profile, ID3, IPTC, 2279 ISO, ITC, JFIF, JPEG, JSON, Jpeg2000, LNK, Leaf, Lytro, M2TS, MIE, MIFF, 2280 MNG, MOI, MPC, MPEG, MPF, MXF, MakerNotes, Matroska, Meta, Ogg, OpenEXR, 2281 Opus, PDF, PICT, PLIST, PNG, PSP, Palm, Parrot, PanasonicRaw, PhotoCD, 2282 PhotoMechanic, Photoshop, PostScript, PrintIM, QuickTime, RAF, RIFF, RSRC, 2283 RTF, Radiance, Rawzor, Real, Red, SVG, SigmaRaw, Stim, Theora, Torrent, 2284 Trailer, UserParam, VCard, Vorbis, WTV, XML, XMP, ZIP 1862 2285 1863 2286 =item Family 1 (Specific Location): 1864 2287 1865 AC3, AFCP, AIFF, APE, ASF, AVI1, Adobe, AdobeCM, CIFF, Canon, CanonCustom, 1866 CanonRaw, CanonVRD, Casio, Chapter#, Composite, DICOM, DNG, DV, DjVu, 1867 DjVu-Meta, Ducky, EPPIM, EXE, EXIF, ExifIFD, ExifTool, FLAC, File, Flash, 1868 FlashPix, Font, FotoStation, FujiFilm, GE, GIF, GIMP, GPS, GeoTiff, 1869 GlobParamIFD, GraphConv, H264, HP, HTML, HTML-dc, HTML-ncc, HTML-office, 2288 AC3, AFCP, AIFF, APE, ASF, AVI1, Adobe, AdobeCM, AdobeDNG, Apple, Audible, 2289 CIFF, CameraIFD, Canon, CanonCustom, CanonRaw, CanonVRD, Casio, Chapter#, 2290 Composite, DICOM, DJI, DNG, DV, DjVu, DjVu-Meta, Ducky, EPPIM, EXE, EXIF, 2291 ExifIFD, ExifTool, FITS, FLAC, FLIR, File, Flash, FlashPix, Font, 2292 FotoStation, FujiFilm, FujiIFD, GE, GIF, GIMP, GPS, GeoTiff, GlobParamIFD, 2293 GoPro, GraphConv, H264, HP, HTC, HTML, HTML-dc, HTML-ncc, HTML-office, 1870 2294 HTML-prod, HTML-vw96, HTTP-equiv, ICC-chrm, ICC-clrt, ICC-header, ICC-meas, 1871 2295 ICC-meta, ICC-view, ICC_Profile, ICC_Profile#, ID3, ID3v1, ID3v1_Enh, 1872 ID3v2_2, ID3v2_3, ID3v2_4, IFD0, IFD1, IPTC, IPTC#, ITC, InteropIFD, JFIF, 1873 JPEG, JVC, Jpeg2000, KDC_IFD, Kodak, KodakBordersIFD, KodakEffectsIFD, 1874 KodakIFD, KyoceraRaw, LNK, Leaf, LeafSubIFD, Leica, M2TS, MAC, MIE-Audio, 1875 MIE-Camera, MIE-Canon, MIE-Doc, MIE-Extender, MIE-Flash, MIE-GPS, MIE-Geo, 1876 MIE-Image, MIE-Lens, MIE-Main, MIE-MakerNotes, MIE-Meta, MIE-Orient, 1877 MIE-Preview, MIE-Thumbnail, MIE-UTM, MIE-Unknown, MIE-Video, MIFF, MNG, MPC, 1878 MPEG, MPF0, MPImage, MXF, MakerNotes, MakerUnknown, Matroska, MetaIFD, 1879 Microsoft, Minolta, MinoltaRaw, NITF, Nikon, NikonCapture, NikonCustom, 1880 NikonScan, Olympus, PDF, PICT, PNG, PSP, Panasonic, Pentax, PhotoMechanic, 1881 Photoshop, PictureInfo, PostScript, PreviewIFD, PrintIM, ProfileIFD, 1882 QuickTime, RAF, RAF2, RIFF, RMETA, RSRC, RTF, Rawzor, Real, Real-CONT, 1883 Real-MDPR, Real-PROP, Real-RA3, Real-RA4, Real-RA5, Real-RJMD, Reconyx, 1884 Ricoh, SPIFF, SR2, SR2DataIFD, SR2SubIFD, SRF#, SVG, Samsung, Sanyo, 1885 Scalado, Sigma, SigmaRaw, Sony, SonyIDC, Stim, SubIFD, System, Track#, 1886 Version0, Vorbis, XML, XMP, XMP-DICOM, XMP-MP, XMP-MP1, XMP-PixelLive, 1887 XMP-acdsee, XMP-album, XMP-aux, XMP-cc, XMP-cell, XMP-crs, XMP-dc, XMP-dex, 1888 XMP-digiKam, XMP-exif, XMP-iptcCore, XMP-iptcExt, XMP-lr, XMP-mediapro, 1889 XMP-microsoft, XMP-mwg-coll, XMP-mwg-kw, XMP-mwg-rs, XMP-pdf, XMP-pdfx, 1890 XMP-photomech, XMP-photoshop, XMP-plus, XMP-prism, XMP-prl, XMP-pur, 2296 ID3v2_2, ID3v2_3, ID3v2_4, IFD0, IFD1, IPTC, IPTC#, ISO, ITC, Insta360, 2297 InteropIFD, ItemList, JFIF, JFXX, JPEG, JPEG-HDR, JSON, JVC, Jpeg2000, 2298 KDC_IFD, Keys, Kodak, KodakBordersIFD, KodakEffectsIFD, KodakIFD, 2299 KyoceraRaw, LNK, Leaf, LeafSubIFD, Leica, Lyrics3, Lytro, M2TS, MAC, 2300 MIE-Audio, MIE-Camera, MIE-Canon, MIE-Doc, MIE-Extender, MIE-Flash, MIE-GPS, 2301 MIE-Geo, MIE-Image, MIE-Lens, MIE-Main, MIE-MakerNotes, MIE-Meta, 2302 MIE-Orient, MIE-Preview, MIE-Thumbnail, MIE-UTM, MIE-Unknown, MIE-Video, 2303 MIFF, MNG, MOBI, MOI, MPC, MPEG, MPF0, MPImage, MS-DOC, MXF, MacOS, 2304 MakerNotes, MakerUnknown, Matroska, MediaJukebox, Meta, MetaIFD, Microsoft, 2305 Minolta, MinoltaRaw, Motorola, NITF, Nikon, NikonCapture, NikonCustom, 2306 NikonScan, NikonSettings, Nintendo, Ocad, Ogg, Olympus, OpenEXR, Opus, PDF, 2307 PICT, PNG, PNG-pHYs, PSP, Palm, Panasonic, PanasonicRaw, Pentax, PhaseOne, 2308 PhotoCD, PhotoMechanic, Photoshop, PictureInfo, PostScript, PreviewIFD, 2309 PrintIM, ProfileIFD, Qualcomm, QuickTime, RAF, RAF2, RIFF, RMETA, RSRC, RTF, 2310 Radiance, Rawzor, Real, Real-CONT, Real-MDPR, Real-PROP, Real-RA3, Real-RA4, 2311 Real-RA5, Real-RJMD, Reconyx, Red, Ricoh, SPIFF, SR2, SR2DataIFD, SR2SubIFD, 2312 SRF#, SVG, Samsung, Sanyo, Scalado, Sigma, SigmaRaw, Sony, SonyIDC, Stim, 2313 SubIFD, System, Theora, Torrent, Track#, UserData, UserParam, VCalendar, 2314 VCard, Version0, Vorbis, WTV, XML, XMP, XMP-DICOM, XMP-Device, XMP-GAudio, 2315 XMP-GDepth, XMP-GFocus, XMP-GImage, XMP-GPano, XMP-GSpherical, XMP-LImage, 2316 XMP-MP, XMP-MP1, XMP-PixelLive, XMP-aas, XMP-acdsee, XMP-album, 2317 XMP-apple-fi, XMP-aux, XMP-cc, XMP-cell, XMP-creatorAtom, XMP-crs, XMP-dc, 2318 XMP-dex, XMP-digiKam, XMP-drone-dji, XMP-dwc, XMP-exif, XMP-exifEX, 2319 XMP-expressionmedia, XMP-extensis, XMP-fpv, XMP-getty, XMP-ics, 2320 XMP-iptcCore, XMP-iptcExt, XMP-lr, XMP-mediapro, XMP-microsoft, 2321 XMP-mwg-coll, XMP-mwg-kw, XMP-mwg-rs, XMP-pdf, XMP-pdfx, XMP-photomech, 2322 XMP-photoshop, XMP-plus, XMP-pmi, XMP-prism, XMP-prl, XMP-prm, XMP-pur, 1891 2323 XMP-rdf, XMP-swf, XMP-tiff, XMP-x, XMP-xmp, XMP-xmpBJ, XMP-xmpDM, XMP-xmpMM, 1892 2324 XMP-xmpNote, XMP-xmpPLUS, XMP-xmpRights, XMP-xmpTPg, ZIP … … 1894 2326 =item Family 2 (Category): 1895 2327 1896 Audio, Author, Camera, D ocument, ExifTool, Image, Location, Other, Printing,1897 Time, Unknown, Video2328 Audio, Author, Camera, Device, Document, ExifTool, Image, Location, Other, 2329 Preview, Printing, Time, Unknown, Video 1898 2330 1899 2331 =item Family 3 (Document Number): … … 1905 2337 Copy# 1906 2338 1907 =back 2339 =item Family 5 (Metadata Path): 2340 2341 eg. JPEG-APP1-IFD0-ExifIFD 2342 2343 =item Family 6 (EXIF/TIFF Format): 2344 2345 int8u, string, int16u, int32u, rational64u, int8s, undef, int16s, int32s, 2346 rational64s, float, double, ifd, unicode, complex, int64u, int64s, ifd64 2347 2348 =item Family 7 (Tag ID): 2349 2350 ID-xxx (Where xxx is the tag ID. Numerical ID's are returned in hex with a 2351 leading "0x" if the HexTagIDs option is set, or decimal otherwise. 2352 Characters in non-numerical ID's which are not valid in a group name are 2353 returned as 2 hex digits.) 2354 2355 =back 2356 2357 Note: This function may also be called as an ExifTool member function to 2358 allow the HexTagIDs option to be set when retrieving family 7 group names. 1908 2359 1909 2360 =head2 GetDeleteGroups [static] … … 1924 2375 deletable group names is: 1925 2376 1926 AFCP, CIFF, CanonVRD, EXIF, ExifIFD, Ducky, File, FlashPix, FotoStation, 1927 GlobParamIFD, GPS, IFD0, IFD1, InteropIFD, ICC_Profile, IPTC, JFIF, 1928 MakerNotes, Meta, MetaIFD, MIE, PhotoMechanic, Photoshop, PNG, PrintIM, 1929 RMETA, SubIFD, Trailer, XMP 1930 1931 All names in this list are either family 0 or family 1 group names, with the 1932 exception of 'Trailer' which allows all trailers in JPEG and TIFF-format 1933 images to be deleted at once, including unknown trailers. To schedule a 1934 group for deletion, call L</SetNewValue> with an undefined value and a tag 1935 name like 'Trailer:*'. 2377 AFCP, APP0, APP1, APP10, APP11, APP12, APP13, APP14, APP15, APP2, APP3, 2378 APP4, APP5, APP6, APP7, APP8, APP9, Adobe, Audio, Author, CIFF, Camera, 2379 CanonVRD, Document, Ducky, EXIF, ExifIFD, ExifTool, File, FlashPix, 2380 FotoStation, GPS, GlobParamIFD, ICC_Profile, IFD0, IFD1, IPTC, Image, 2381 InteropIFD, JFIF, Jpeg2000, Location, MIE, MPF, MakerNotes, Meta, MetaIFD, 2382 NikonCapture, Other, PDF, PDF-update, PNG, PNG-pHYs, PhotoMechanic, 2383 Photoshop, Preview, PrintIM, Printing, RMETA, RSRC, SubIFD, Time, Trailer, 2384 Video, XML, XML-*, XMP, XMP-* 2385 2386 To schedule a group for deletion, call L</SetNewValue> with a tag name like 2387 'EXIF:*' and an undefined tag value. 2388 2389 Deleting a family 0 or 1 group will delete the entire corresponding block of 2390 metadata, but deleting a family 2 group (eg. Audio, Author, Camera, etc.) 2391 deletes the individual tags belonging to that category. 2392 2393 The 'Trailer' group allows all trailers in JPEG and TIFF-format images to be 2394 deleted at once, including unknown trailers. Note that the JPEG "APP" 2395 groups are special, and are used only to delete application segments which 2396 are not associated with another deletable group. For example, deleting 2397 'APP14:*' will delete other APP14 segments, but not the APP14 "Adobe" 2398 segment. 1936 2399 1937 2400 =back … … 1950 2413 0) [optional] File name (or just an extension) 1951 2414 1952 1) [optional] Flag to return a description instead of a type. Set to 0 to 1953 return type for recognized but unsupported files (otherwise the return value 1954 for unsupported files is undef). 2415 1) [optional] Flag to return a description instead of a type. Default is 2416 undef. Set to 0 to also return types of recognized but unsupported files 2417 (otherwise the return value for unsupported files is undef), or 1 to return 2418 descriptions. 1955 2419 1956 2420 =item Return Value: … … 1958 2422 A string, based on the file extension, which indicates the basic format of 1959 2423 the file. Note that some files may be based on other formats (like many RAW 1960 image formats are based on TIFF). In array context, may return more than1961 one file type if the file may be based on different formats. Returns undef1962 if files with this extension are not yet supported by ExifTool. Returns a 1963 listof extensions for all supported file types if no input extension is1964 specified (or all recognized file types if the description flag is set to 0).1965 Returns a more detailed description of the specific file format when the2424 image formats are based on TIFF). In list context, may return more than one 2425 file type if the file may be based on different formats. Returns undef if 2426 files with this extension are not yet supported by ExifTool. Returns a list 2427 of extensions for all supported file types if no input extension is 2428 specified (or all recognized file types if the description flag is set to 2429 0). Returns a more detailed description of the specific file format when the 1966 2430 description flag is set. 1967 2431 … … 2001 2465 =item Return Value: 2002 2466 2003 True if ExifTool can create files with this extension from scratch. 2004 Currently, this can only be done with XMP, MIE, ICC, VRD and EXIF files. 2467 True if ExifTool can create files with this extension from scratch. 2468 Currently, this can only be done with XMP, MIE, ICC, VRD, DR4, EXV and EXIF 2469 files. 2470 2471 =back 2472 2473 =head2 AddUserDefinedTags [static] 2474 2475 Add user-defined tags to an existing tag table at run time. This differs 2476 from the usual technique of creating user-defined tags via the 2477 %Image::ExifTool::UserDefined hash (see the ExifTool_config file in the 2478 Image::ExifTool distribution) because it allows tags to be added after a tag 2479 table has been initialized. 2480 2481 use Image::ExifTool ':Public'; 2482 my %tags = ( 2483 TestTagID1 => { Name => 'TestTagName1' }, 2484 TestTagID2 => { Name => 'TestTagName2' }, 2485 ); 2486 my $num = AddUserDefinedTags('Image::ExifTool::PDF::Info', %tags); 2487 2488 =over 4 2489 2490 =item Inputs: 2491 2492 0) Destination tag table name 2493 2494 1-N) Pairs of tag ID / tag information hash references for the new tags 2495 2496 =item Return Value: 2497 2498 The number of tags added. 2499 2500 =item Notes 2501 2502 Pre-existing tags with the same ID will be replaced in the destination 2503 table. See lib/Image/ExifTool/README in the full distribution for full 2504 details on the elements of the tag information hash. 2005 2505 2006 2506 =back … … 2009 2509 2010 2510 Certain meta information formats allow coded character sets other than plain 2011 ASCII. When reading, 8-bit encodings are passed straight through ExifTool 2012 without re-coding unless specified otherwise below, and multi-byte encodings 2013 are converted according to the L</Charset> option ('UTF8' by default). When 2014 writing, the inverse conversions are performed. See the L</Charset> option 2015 for a list of valid character sets. 2511 ASCII. When reading, most known encodings are converted to the external 2512 character set according to the L</Charset> option, or to UTF-8 by default. 2513 When writing, the inverse conversions are performed. Alternatively, special 2514 characters may be converted to/from HTML character entities with the 2515 L</Escape> HTML option. 2516 2517 A distinction is made between the external character set visible via the 2518 ExifTool API, and the internal character used to store text in the metadata 2519 of a file. These character sets may be specified separately as follows: 2520 2521 =over 4 2522 2523 =item External Character Sets: 2524 2525 The encoding for tag values passed to/from ExifTool API functions is set via 2526 the L</Charset> option, which is 'UTF8' by default. 2527 2528 The encoding of file names is specified via the L</CharsetFileName> option. 2529 By default, L</CharsetFileName> is not defined, and file names passed to 2530 ExifTool are used directly in calls to the system i/o routines (which expect 2531 UTF-8 strings on Mac/Linux, but default to the system code page on Windows). 2532 In this mode on Windows a warning is issued if a file name contains special 2533 characters, but this warning may be avoided by setting L</CharsetFileName> 2534 to an empty string. Setting L</CharsetFileName> to any other value causes 2535 file names to be converted from the specified encoding to one appropriate 2536 for the system. In Windows this also has the effect of activating Unicode 2537 filename support via the special Windows wide-character i/o routines if 2538 Win32API::File is available. 2539 2540 =item Internal Character Sets: 2541 2542 The encodings used to store strings in the various metadata formats. These 2543 encodings may be changed for certain types of metadata via the 2544 L</CharsetEXIF>, L</CharsetID3>, L</CharsetIPTC>, L</CharsetPhotoshop>, 2545 L</CharsetQuickTime> and L</CharsetRIFF> options. 2546 2547 =back 2548 2549 Values are returned as byte strings of encoded characters. Perl wide 2550 characters are not used. By default, most returned strings are encoded in 2551 UTF-8. For these, Encode::decode_utf8() may be used to convert to a 2552 sequence of logical Perl characters. Note that some settings of the 2553 PERL_UNICODE environment variable may be incompatible with ExifTool's 2554 character handling. 2016 2555 2017 2556 More specific details are given below about how character coding is handled 2018 for EXIF, IPTC, XMP, PNG, ID3, PDF and MIE information: 2557 for EXIF, IPTC, XMP, PNG, ID3, PDF, Photoshop, QuickTime, AIFF, MIE and 2558 Vorbis information: 2019 2559 2020 2560 =head2 EXIF 2021 2561 2022 Most textual information in EXIF is stored in ASCII format, and ExifTool 2023 does not convert these tags. However it is not uncommon for applications to 2024 write UTF-8 or other encodings where ASCII is expected, and ExifTool will 2025 quite happily read/write any encoding without conversion. For a few EXIF 2026 tags (UserComment, GPSProcessingMethod and GPSAreaInformation) the stored 2027 text may be encoded either in ASCII, Unicode (UCS-2) or JIS. When reading 2028 these tags, Unicode and JIS are converted to the character set specified by 2029 the L</Charset> option. Other encodings are not converted. When writing, 2562 Most textual information in EXIF is stored in ASCII format (called "string" 2563 in the L<ExifTool tag name documentation|Image::ExifTool::TagNames>). By 2564 default ExifTool does not convert these strings. However, it is not 2565 uncommon for applications to write UTF-8 or other encodings where ASCII is 2566 expected. To deal with these, ExifTool allows the internal EXIF string 2567 encoding to be specified with L</CharsetEXIF>, which causes EXIF string 2568 values to be converted from the specified character set when reading, and 2569 stored with this character set when writing. (The MWG recommends using 2570 UTF-8 encoding for EXIF strings, and in keeping with this the 2571 L<MWG|Image::ExifTool::MWG> module sets the default internal EXIF string 2572 encoding to UTF-8, but note that this will have no effect unless the 2573 external encoding is also set to something other than the default of UTF-8.) 2574 2575 A few EXIF tags (UserComment, GPSProcessingMethod and GPSAreaInformation) 2576 support a designated internal text encoding, with values stored as ASCII, 2577 Unicode (UCS-2) or JIS. When reading these tags, ExifTool converts Unicode 2578 and JIS to the external character set specified by the L</Charset> 2579 option, or to UTF-8 by default. ASCII text is not converted. When writing, 2030 2580 text is stored as ASCII unless the string contains special characters, in 2031 which case it is converted from the specified character set and stored as 2032 Unicode. ExifTool writes Unicode in native EXIF byte ordering by default, 2033 but this may be changed by setting the ExifUnicodeByteOrder tag. The EXIF 2034 "XP" tags (XPTitle, XPComment, etc) are always stored as little-endian 2035 Unicode, and are read and written using the specified character set. 2581 which case it is converted from the external character set (UTF-8 by 2582 default), and stored as Unicode. ExifTool writes Unicode in native EXIF byte 2583 ordering by default, but the byte order may be specified by setting the 2584 ExifUnicodeByteOrder tag (see the 2585 L<Extra Tags documentation|Image::ExifTool::TagNames/Extra Tags>). 2586 2587 The EXIF "XP" tags (XPTitle, XPComment, etc) are always stored as 2588 little-endian Unicode (UCS-2), and are read and written using the specified 2589 character set. 2036 2590 2037 2591 =head2 IPTC … … 2047 2601 character sets are the same. Note that ISO 2022 character set shifting is 2048 2602 not supported. Instead, a warning is issued and the string is not converted 2049 if an ISO 2022 shift code is found. See L<http://www.iptc.org/IIM/> for the 2050 official IPTC specification. 2603 if an ISO 2022 shift code is encountered. See L<http://www.iptc.org/IIM/> 2604 for the official IPTC specification. 2605 2606 ExifTool may be used to convert IPTC values to a different internal 2607 encoding. To do this, all IPTC tags must be rewritten along with the 2608 desired value of CodedCharacterSet. For example, the following command 2609 changes the internal IPTC encoding to UTF-8 (from Windows Latin1 unless 2610 CodedCharacterSet was already 'UTF8'): 2611 2612 exiftool -tagsfromfile @ -iptc:all -codedcharacterset=utf8 a.jpg 2613 2614 or from Windows Latin2 (cp1250) to UTF-8: 2615 2616 exiftool -tagsfromfile @ -iptc:all -codedcharacterset=utf8 \ 2617 -charset iptc=latin2 a.jpg 2618 2619 and this command changes it back from UTF-8 to Windows Latin1 (cp1252): 2620 2621 exiftool -tagsfromfile @ -iptc:all -codedcharacterset= a.jpg 2622 2623 or to Windows Latin2: 2624 2625 exiftool -tagsfromfile @ -iptc:all -codedcharacterset= \ 2626 -charset iptc=latin2 a.jpg 2627 2628 Unless CodedCharacterSet is 'UTF8', applications have no reliable way to 2629 determine the IPTC character encoding. For this reason, it is recommended 2630 that CodedCharacterSet be set to 'UTF8' when creating new IPTC. 2631 2632 (Note: Here, "IPTC" Refers to the older IPTC IIM format. The more recent 2633 IPTC Core and Extension specifications actually use the XMP format.) 2051 2634 2052 2635 =head2 XMP 2053 2636 2054 Exif tool reads XMP encoded as UTF-8, UTF-16 or UTF-32, and converts them all2637 ExifTool reads XMP encoded as UTF-8, UTF-16 or UTF-32, and converts them all 2055 2638 to UTF-8 internally. Also, all XML character entity references and numeric 2056 2639 character references are converted. When writing, ExifTool always encodes … … 2058 2641 references: E<amp> E<lt> E<gt> E<39> E<quot>. By default no further 2059 2642 conversion is performed, however if the L</Charset> option is other than 2060 'UTF8' then text is converted to/from aspecified character set when2643 'UTF8' then text is converted to/from the specified character set when 2061 2644 reading/writing. 2062 2645 … … 2072 2655 text is converted from the specified character set and stored as UTF-8. 2073 2656 2657 =head2 JPEG Comment 2658 2659 The encoding for the JPEG Comment (COM segment) is not specified, so 2660 ExifTool reads/writes this text without conversion. 2661 2074 2662 =head2 ID3 2075 2663 … … 2077 2665 subset of Windows Latin1), although some applications may incorrectly use 2078 2666 other character sets. By default ExifTool converts ID3v1 text from Latin to 2079 the character set specified by the </Charset> option. However, the internal2080 ID3v1 charset may be specified with the L</CharsetID3> option. The encoding 2081 for ID3v2 information is stored in the file, so ExifTool converts ID3v2 text 2082 from this encoding to the character set specified by the L</Charset> option. 2083 ExifTool does not currently write ID3 information.2667 the character set specified by the L</Charset> option. However, the 2668 internal ID3v1 charset may be specified with the L</CharsetID3> option. The 2669 encoding for ID3v2 information is stored in the file, so ExifTool converts 2670 ID3v2 text from this encoding to the character set specified by the 2671 L</Charset> option. ExifTool does not currently write ID3 information. 2084 2672 2085 2673 =head2 PDF … … 2090 2678 encodes input text from the specified character set as Unicode only if the 2091 2679 string contains special characters, otherwise PDFDocEncoding is used. 2680 2681 =head2 Photoshop 2682 2683 Some Photoshop resource names are stored as Pascal strings with unknown 2684 encoding. By default, ExifTool assumes MacRoman encoding and converts this 2685 to UTF-8, but the internal and external character sets may be specified with 2686 the L</CharsetPhotoshop> and L</Charset> options respectively. 2687 2688 =head2 QuickTime 2689 2690 QuickTime text strings may be stored in a variety of poorly document 2691 formats. ExifTool does its best to decode these according to the L</Charset> 2692 option setting. For some QuickTime strings, ExifTool assumes a default 2693 encoding of MacRoman, but this may be changed with the L</CharsetQuickTime> 2694 option. 2695 2696 =head2 AIFF 2697 2698 AIFF strings are assumed to be stored in MacRoman, and are converted 2699 according to the L</Charset> option when reading. 2700 2701 =head2 RIFF 2702 2703 The internal encoding of RIFF strings (eg. in AVI and WAV files) is assumed 2704 to be Latin unless otherwise specified by the RIFF CSET chunk or the 2705 L</CharsetRIFF> option. 2092 2706 2093 2707 =head2 MIE … … 2100 2714 are stored as ISO 8859-1. 2101 2715 2716 =head2 Vorbis 2717 2718 Vorbis comments are stored as UTF-8, and are converted to the character set 2719 specified by the L</Charset> option. 2720 2102 2721 =head1 AUTHOR 2103 2722 2104 Copyright 2003-20 11, Phil Harvey2723 Copyright 2003-2021, Phil Harvey 2105 2724 2106 2725 This library is free software; you can redistribute it and/or modify it … … 2120 2739 L<Image::ExifTool::TagNames(3pm)|Image::ExifTool::TagNames>, 2121 2740 L<Image::ExifTool::Shortcuts(3pm)|Image::ExifTool::Shortcuts>, 2122 L<Image::ExifTool::Shift .pl|Image::ExifTool::Shift.pl>,2741 L<Image::ExifTool::Shift(3pm)|Image::ExifTool::Shift.pl>, 2123 2742 L<Image::Info(3pm)|Image::Info>, 2124 2743 L<Image::MetaData::JPEG(3pm)|Image::MetaData::JPEG>
Note:
See TracChangeset
for help on using the changeset viewer.