1 | #------------------------------------------------------------------------------
|
---|
2 | # File: ExifTool.pod - Documentation for File::ExifTool
|
---|
3 | #
|
---|
4 | # Description: Read and write meta information
|
---|
5 | #
|
---|
6 | # URL: https://exiftool.org/
|
---|
7 | #
|
---|
8 | # Legal: Copyright (c) 2003-2021, Phil Harvey (philharvey66 at gmail.com)
|
---|
9 | # This library is free software; you can redistribute it and/or
|
---|
10 | # modify it under the same terms as Perl itself.
|
---|
11 | #------------------------------------------------------------------------------
|
---|
12 |
|
---|
13 | =head1 NAME
|
---|
14 |
|
---|
15 | Image::ExifTool - Read and write meta information
|
---|
16 |
|
---|
17 | =head1 SYNOPSIS
|
---|
18 |
|
---|
19 | use Image::ExifTool qw(:Public);
|
---|
20 |
|
---|
21 | # ---- Simple procedural usage ----
|
---|
22 |
|
---|
23 | # Get hash of meta information tag names/values from an image
|
---|
24 | $info = ImageInfo('a.jpg');
|
---|
25 |
|
---|
26 | # ---- Object-oriented usage ----
|
---|
27 |
|
---|
28 | # Create a new Image::ExifTool object
|
---|
29 | $exifTool = new Image::ExifTool;
|
---|
30 |
|
---|
31 | # Extract meta information from an image
|
---|
32 | $exifTool->ExtractInfo($file, \%options);
|
---|
33 |
|
---|
34 | # Get list of tags in the order they were found in the file
|
---|
35 | @tagList = $exifTool->GetFoundTags('File');
|
---|
36 |
|
---|
37 | # Get the value of a specified tag
|
---|
38 | $value = $exifTool->GetValue($tag, $type);
|
---|
39 |
|
---|
40 | # Get a tag description
|
---|
41 | $description = $exifTool->GetDescription($tag);
|
---|
42 |
|
---|
43 | # Get the group name associated with this tag
|
---|
44 | $group = $exifTool->GetGroup($tag, $family);
|
---|
45 |
|
---|
46 | # Set a new value for a tag
|
---|
47 | $exifTool->SetNewValue($tag, $newValue);
|
---|
48 |
|
---|
49 | # Write new meta information to a file
|
---|
50 | $success = $exifTool->WriteInfo($srcfile, $dstfile);
|
---|
51 |
|
---|
52 | # ...plus a host of other useful methods...
|
---|
53 |
|
---|
54 | =head1 DESCRIPTION
|
---|
55 |
|
---|
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 |
|
---|
63 | Below is a list of file types and meta information formats currently
|
---|
64 | supported by ExifTool (r = read, w = write, c = create):
|
---|
65 |
|
---|
66 | File Types
|
---|
67 | ------------+-------------+-------------+-------------+------------
|
---|
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 |
|
---|
109 |
|
---|
110 | Meta Information
|
---|
111 | ----------------------+----------------------+---------------------
|
---|
112 | EXIF r/w/c | CIFF r/w | Ricoh RMETA r
|
---|
113 | GPS r/w/c | AFCP r/w | Picture Info r
|
---|
114 | IPTC r/w/c | Kodak Meta r/w | Adobe APP14 r
|
---|
115 | XMP r/w/c | FotoStation r/w | MPF r
|
---|
116 | MakerNotes r/w/c | PhotoMechanic r/w | Stim r
|
---|
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)
|
---|
127 |
|
---|
128 | =head1 CONFIGURATION
|
---|
129 |
|
---|
130 | User-defined tags can be added via the ExifTool configuration file, or by
|
---|
131 | defining the %Image::ExifTool::UserDefined hash before calling any ExifTool
|
---|
132 | methods. See "ExifTool_config" in the ExifTool distribution for more
|
---|
133 | details.
|
---|
134 |
|
---|
135 | By default ExifTool looks for a configuration file named ".ExifTool_config"
|
---|
136 | first in your home directory, then in the directory of the application
|
---|
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:
|
---|
141 |
|
---|
142 | BEGIN { $Image::ExifTool::configFile = '/Users/phil/myconfig.cfg' }
|
---|
143 | use Image::ExifTool;
|
---|
144 |
|
---|
145 | The configuration feature may also be disabled by setting C<configFile> to
|
---|
146 | an empty string:
|
---|
147 |
|
---|
148 | BEGIN { $Image::ExifTool::configFile = '' }
|
---|
149 | use Image::ExifTool;
|
---|
150 |
|
---|
151 | =head1 EXPORTS
|
---|
152 |
|
---|
153 | Exports nothing by default, but L</ImageInfo> and all static methods may be
|
---|
154 | exported with the C<:Public> export list.
|
---|
155 |
|
---|
156 | =head1 METHODS
|
---|
157 |
|
---|
158 | All ExifTool features are accessed through the methods of the public
|
---|
159 | interface listed below. Other Image::ExifTool methods and modules should
|
---|
160 | not be accessed directly because their interface may change with future
|
---|
161 | versions.
|
---|
162 |
|
---|
163 | None of these methods should ever die or issue warnings to STDERR if called
|
---|
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.
|
---|
172 |
|
---|
173 | =head2 new
|
---|
174 |
|
---|
175 | Creates a new ExifTool object.
|
---|
176 |
|
---|
177 | $exifTool = new Image::ExifTool;
|
---|
178 |
|
---|
179 | Note that ExifTool uses AUTOLOAD to load non-member methods, so any class
|
---|
180 | using Image::ExifTool as a base class must define an AUTOLOAD which calls
|
---|
181 | Image::ExifTool::DoAutoLoad(). eg)
|
---|
182 |
|
---|
183 | sub AUTOLOAD
|
---|
184 | {
|
---|
185 | Image::ExifTool::DoAutoLoad($AUTOLOAD, @_);
|
---|
186 | }
|
---|
187 |
|
---|
188 | =head2 ImageInfo
|
---|
189 |
|
---|
190 | Read image file and return meta information. This is the one step function
|
---|
191 | for retrieving meta information from an image. Internally, L</ImageInfo>
|
---|
192 | calls L</ExtractInfo> to extract the information, L</GetInfo> to generate
|
---|
193 | the information hash, and L</GetTagList> for the returned tag list.
|
---|
194 |
|
---|
195 | # return meta information for 2 tags only (procedural)
|
---|
196 | $info = ImageInfo($filename, $tag1, $tag2);
|
---|
197 |
|
---|
198 | # return information about an open image file (object-oriented)
|
---|
199 | $info = $exifTool->ImageInfo(\*FILE);
|
---|
200 |
|
---|
201 | # return information from image data in memory for specified tags
|
---|
202 | %options = (PrintConv => 0);
|
---|
203 | @tagList = qw(filename imagesize xmp:creator exif:* -ifd1:*);
|
---|
204 | $info = ImageInfo(\$imageData, \@tagList, \%options);
|
---|
205 |
|
---|
206 | # extract information from an embedded thumbnail image
|
---|
207 | $info = ImageInfo('image.jpg', 'thumbnailimage');
|
---|
208 | $thumbInfo = ImageInfo($$info{ThumbnailImage});
|
---|
209 |
|
---|
210 | =over 4
|
---|
211 |
|
---|
212 | =item Inputs:
|
---|
213 |
|
---|
214 | L</ImageInfo> is very flexible about the input arguments, and interprets
|
---|
215 | them based on their type. It may be called with one or more arguments.
|
---|
216 | The one required argument is either a SCALAR (the image file name), a file
|
---|
217 | reference (a reference to the image file) or a SCALAR reference (a
|
---|
218 | reference to the image in memory). Other arguments are optional. The
|
---|
219 | order of the arguments is not significant, except that the first SCALAR is
|
---|
220 | taken to be the file name unless a file reference or scalar reference comes
|
---|
221 | earlier in the argument list.
|
---|
222 |
|
---|
223 | Below is an explanation of how the L</ImageInfo> function arguments are
|
---|
224 | interpreted:
|
---|
225 |
|
---|
226 | =over 4
|
---|
227 |
|
---|
228 | =item ExifTool ref
|
---|
229 |
|
---|
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.
|
---|
234 |
|
---|
235 | =item SCALAR
|
---|
236 |
|
---|
237 | The first scalar argument is taken to be the file name unless an earlier
|
---|
238 | argument specified the image data via a file reference (file ref) or data
|
---|
239 | reference (SCALAR ref). The remaining scalar arguments are names of tags
|
---|
240 | for requested information. All tags are returned if no tags are specified.
|
---|
241 |
|
---|
242 | Tag names are case-insensitive and may be prefixed by optional group names
|
---|
243 | separated by colons. A group name may begin with a family number (eg.
|
---|
244 | '1IPTC:Keywords'), to restrict matches to a specific family. In the tag
|
---|
245 | name, a '?' matches any single character and a '*' matches zero or more
|
---|
246 | characters. Thus 'GROUP:*' represents all tags in a specific group.
|
---|
247 | Wildcards may not be used in group names, with the exception that a group
|
---|
248 | name of '*' may be used to extract all available instances of a tag
|
---|
249 | 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
|
---|
252 | trailing '#' causes the ValueConv value to be returned for this tag.
|
---|
253 |
|
---|
254 | Note that keys in the returned information hash and elements of the returned
|
---|
255 | tag list are not necessarily the same as these tag names because group names
|
---|
256 | are removed, the case may be changed, and an instance number may be added.
|
---|
257 | For this reason it is best to use either the keys of the returned hash or
|
---|
258 | the elements of the returned tag list when accessing the tag values.
|
---|
259 |
|
---|
260 | See L<Image::ExifTool::TagNames|Image::ExifTool::TagNames> for a complete
|
---|
261 | list of ExifTool tag names.
|
---|
262 |
|
---|
263 | =item File ref
|
---|
264 |
|
---|
265 | A reference to an open image file. If you use this method (or a SCALAR
|
---|
266 | reference) to access information in an image, the FileName and Directory
|
---|
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
|
---|
275 | re-read after processing with ExifTool, first wrap the file reference in a
|
---|
276 | L<File::RandomAccess|File::RandomAccess> object, then pass this object to
|
---|
277 | L</ImageInfo>. The L<File::RandomAccess|File::RandomAccess> object will
|
---|
278 | buffer the file if necessary, and may be used to re-read the file after
|
---|
279 | L</ImageInfo> returns.]
|
---|
280 |
|
---|
281 | =item SCALAR ref
|
---|
282 |
|
---|
283 | A reference to image data in memory.
|
---|
284 |
|
---|
285 | =item ARRAY ref
|
---|
286 |
|
---|
287 | Reference to a list of tag names. On entry, any elements in the list are
|
---|
288 | added to the list of requested tags. Tags with names beginning with '-' are
|
---|
289 | excluded. On return, this list is updated to contain an ordered list of tag
|
---|
290 | keys for the returned information.
|
---|
291 |
|
---|
292 | There will be 1:1 correspondence between the requested tags and the returned
|
---|
293 | tag keys only if the L</Duplicates> option is 0 and L</Sort> is 'Input'.
|
---|
294 | (With L</Duplicates> enabled, there may be more entries in the returned list
|
---|
295 | of tag keys, and with other L</Sort> settings the entries may not be in the
|
---|
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.
|
---|
298 |
|
---|
299 | =item HASH ref
|
---|
300 |
|
---|
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.
|
---|
305 |
|
---|
306 | =back
|
---|
307 |
|
---|
308 | =item Return Values:
|
---|
309 |
|
---|
310 | 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
|
---|
313 | from the image. Many of the ExifTool functions require a tag key as an
|
---|
314 | argument. Use L</GetTagName [static]> to get the tag name for a given tag
|
---|
315 | key. Note that the case of the tag names may not be the same as requested.
|
---|
316 | Here is a simple example to print out the information returned by
|
---|
317 | L</ImageInfo>:
|
---|
318 |
|
---|
319 | foreach (sort keys %$info) {
|
---|
320 | print "$_ => $$info{$_}\n";
|
---|
321 | }
|
---|
322 |
|
---|
323 | Values of the returned hash are usually simple scalars, but a scalar
|
---|
324 | reference is used to indicate binary data and an array reference may be used
|
---|
325 | to indicate a list. Also, a hash reference may be returned if the L</Struct>
|
---|
326 | option is used. Lists of values are joined by commas into a single
|
---|
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".
|
---|
332 |
|
---|
333 | The code below gives an example of how to handle these return values, as
|
---|
334 | well as illustrating the use of other ExifTool functions:
|
---|
335 |
|
---|
336 | use Image::ExifTool;
|
---|
337 | my $exifTool = new Image::ExifTool;
|
---|
338 | $exifTool->Options(Unknown => 1);
|
---|
339 | my $info = $exifTool->ImageInfo('a.jpg');
|
---|
340 | my $group = '';
|
---|
341 | my $tag;
|
---|
342 | foreach $tag ($exifTool->GetFoundTags('Group0')) {
|
---|
343 | if ($group ne $exifTool->GetGroup($tag)) {
|
---|
344 | $group = $exifTool->GetGroup($tag);
|
---|
345 | print "---- $group ----\n";
|
---|
346 | }
|
---|
347 | my $val = $info->{$tag};
|
---|
348 | if (ref $val eq 'SCALAR') {
|
---|
349 | if ($$val =~ /^Binary data/) {
|
---|
350 | $val = "($$val)";
|
---|
351 | } else {
|
---|
352 | my $len = length($$val);
|
---|
353 | $val = "(Binary data $len bytes)";
|
---|
354 | }
|
---|
355 | }
|
---|
356 | printf("%-32s : %s\n", $exifTool->GetDescription($tag), $val);
|
---|
357 | }
|
---|
358 |
|
---|
359 | =item Notes:
|
---|
360 |
|
---|
361 | ExifTool returns all values as byte strings of encoded characters. Perl
|
---|
362 | wide characters are not used. See L</CHARACTER ENCODINGS> for details about
|
---|
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:
|
---|
370 |
|
---|
371 | ExifToolVersion - The ExifTool version number.
|
---|
372 |
|
---|
373 | Error - An error message if the image could not be processed.
|
---|
374 |
|
---|
375 | Warning - A warning message if problems were encountered while
|
---|
376 | processing the image.
|
---|
377 |
|
---|
378 | =back
|
---|
379 |
|
---|
380 | =head2 Options
|
---|
381 |
|
---|
382 | Get/set ExifTool options. This function can be called to set the default
|
---|
383 | options for an ExifTool object. Options set this way are in effect for
|
---|
384 | all function calls but may be overridden by options passed as arguments
|
---|
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.
|
---|
390 |
|
---|
391 | # exclude the 'OwnerName' tag from returned information
|
---|
392 | $exifTool->Options(Exclude => 'OwnerName');
|
---|
393 |
|
---|
394 | # only get information in EXIF or MakerNotes groups
|
---|
395 | $exifTool->Options(Group0 => ['EXIF', 'MakerNotes']);
|
---|
396 |
|
---|
397 | # ignore information from IFD1
|
---|
398 | $exifTool->Options(Group1 => '-IFD1');
|
---|
399 |
|
---|
400 | # sort by groups in family 2, and extract unknown tags
|
---|
401 | $exifTool->Options(Sort => 'Group2', Unknown => 1);
|
---|
402 |
|
---|
403 | # reset DateFormat option
|
---|
404 | $exifTool->Options(DateFormat => undef);
|
---|
405 |
|
---|
406 | # do not extract duplicate tag names
|
---|
407 | $oldSetting = $exifTool->Options(Duplicates => 0);
|
---|
408 |
|
---|
409 | # get current Verbose setting
|
---|
410 | $isVerbose = $exifTool->Options('Verbose');
|
---|
411 |
|
---|
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
|
---|
426 |
|
---|
427 | =item Option Parameters:
|
---|
428 |
|
---|
429 | Note that these API options may also be used in the exiftool application via
|
---|
430 | the command-line B<-api> option.
|
---|
431 |
|
---|
432 | =over 4
|
---|
433 |
|
---|
434 | =item Binary
|
---|
435 |
|
---|
436 | Flag to extract the value data for all binary tags. Tag values representing
|
---|
437 | large binary data blocks (eg. ThumbnailImage) are not necessarily extracted
|
---|
438 | unless this option is set or the tag is specifically requested by name.
|
---|
439 | Default is undef.
|
---|
440 |
|
---|
441 | =item ByteOrder
|
---|
442 |
|
---|
443 | The byte order for newly created EXIF segments when writing. Note that if
|
---|
444 | EXIF information already exists, the existing order is maintained. Valid
|
---|
445 | values are 'MM', 'II' and undef. If ByteOrder is not defined (the default),
|
---|
446 | then the maker note byte order is used (if they are being copied), otherwise
|
---|
447 | big-endian ('MM') order is assumed. This can also be set via the
|
---|
448 | L<ExifByteOrder tag|Image::ExifTool::TagNames/Extra Tags>, but the ByteOrder
|
---|
449 | option takes precedence if both are set.
|
---|
450 |
|
---|
451 | =item Charset
|
---|
452 |
|
---|
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:
|
---|
456 |
|
---|
457 | Value Alias(es) Description
|
---|
458 | ----------- --------------- ----------------------------------
|
---|
459 | UTF8 cp65001, UTF-8 UTF-8 characters
|
---|
460 | Latin cp1252, Latin1 Windows Latin1 (West European)
|
---|
461 | Latin2 cp1250 Windows Latin2 (Central European)
|
---|
462 | Cyrillic cp1251, Russian Windows Cyrillic
|
---|
463 | Greek cp1253 Windows Greek
|
---|
464 | Turkish cp1254 Windows Turkish
|
---|
465 | Hebrew cp1255 Windows Hebrew
|
---|
466 | Arabic cp1256 Windows Arabic
|
---|
467 | Baltic cp1257 Windows Baltic
|
---|
468 | Vietnam cp1258 Windows Vietnamese
|
---|
469 | Thai cp874 Windows Thai
|
---|
470 | DOSLatinUS cp437 DOS Latin US
|
---|
471 | DOSLatin1 cp850 DOS Latin1
|
---|
472 | DOSCyrillic cp866 DOS Cyrillic
|
---|
473 | MacRoman cp10000, Roman Macintosh Roman
|
---|
474 | MacLatin2 cp10029 Macintosh Latin2 (Central Europe)
|
---|
475 | MacCyrillic cp10007 Macintosh Cyrillic
|
---|
476 | MacGreek cp10006 Macintosh Greek
|
---|
477 | MacTurkish cp10081 Macintosh Turkish
|
---|
478 | MacRomanian cp10010 Macintosh Romanian
|
---|
479 | MacIceland cp10079 Macintosh Icelandic
|
---|
480 | MacCroatian cp10082 Macintosh Croatian
|
---|
481 |
|
---|
482 | Note that this option affects some types of information when reading/writing
|
---|
483 | the file and other types when getting/setting tag values, so it must be
|
---|
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.
|
---|
499 |
|
---|
500 | =item CharsetID3
|
---|
501 |
|
---|
502 | Internal encoding to assume for ID3v1 strings. By the specification ID3v1
|
---|
503 | strings should be encoded in ISO 8859-1 (essentially Latin), but some
|
---|
504 | applications may use local encoding instead. Default is 'Latin'.
|
---|
505 |
|
---|
506 | =item CharsetIPTC
|
---|
507 |
|
---|
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'.
|
---|
511 |
|
---|
512 | Note that this option affects some types of information when reading/writing
|
---|
513 | the file and other types when getting/setting tag values, so it must be
|
---|
514 | defined for both types of access.
|
---|
515 |
|
---|
516 | =item CharsetPhotoshop
|
---|
517 |
|
---|
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.
|
---|
532 |
|
---|
533 | =item Compact
|
---|
534 |
|
---|
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'
|
---|
551 |
|
---|
552 | =item Composite
|
---|
553 |
|
---|
554 | Flag to generate Composite tags when extracting information. Default is 1.
|
---|
555 |
|
---|
556 | =item Compress
|
---|
557 |
|
---|
558 | Flag to write new values in compressed format if possible. Has no effect
|
---|
559 | unless Compress::Zlib is installed. Default is undef.
|
---|
560 |
|
---|
561 | =item CoordFormat
|
---|
562 |
|
---|
563 | Format for printing GPS coordinates. This is a printf format string with
|
---|
564 | specifiers for degrees, minutes and seconds in that order, however minutes
|
---|
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:
|
---|
570 |
|
---|
571 | CoordFormat Example Output
|
---|
572 | ------------------- ------------------
|
---|
573 | q{%d deg %d' %.2f"} 54 deg 59' 22.80" (default for reading)
|
---|
574 | q{%d %d %.8f} 54 59 22.80000000 (default for copying)
|
---|
575 | q{%d deg %.4f min} 54 deg 59.3800 min
|
---|
576 | q{%.6f degrees} 54.989667 degrees
|
---|
577 |
|
---|
578 | Note: To avoid loss of precision, the default coordinate format is
|
---|
579 | different when copying tags with L</SetNewValuesFromFile>.
|
---|
580 |
|
---|
581 | =item DateFormat
|
---|
582 |
|
---|
583 | Format for printing date/time values. See C<strftime> in the L<POSIX>
|
---|
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").
|
---|
590 |
|
---|
591 | =item Duplicates
|
---|
592 |
|
---|
593 | Flag to return values from tags with duplicate names when extracting
|
---|
594 | information. Default is 1.
|
---|
595 |
|
---|
596 | =item Escape
|
---|
597 |
|
---|
598 | Escape special characters in extracted values for HTML or XML. Also
|
---|
599 | unescapes HTML or XML character entities in input values passed to
|
---|
600 | L</SetNewValue>. Valid settings are 'HTML', 'XML' or undef. Default is
|
---|
601 | undef.
|
---|
602 |
|
---|
603 | =item Exclude
|
---|
604 |
|
---|
605 | Exclude specified tags from tags extracted from an image. The option value
|
---|
606 | is either a tag name or reference to a list of tag names to exclude. The
|
---|
607 | case of tag names is not significant. This option is ignored for
|
---|
608 | specifically requested tags. Tags may also be excluded by preceding their
|
---|
609 | name with a '-' in the arguments to L</ImageInfo>.
|
---|
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 |
|
---|
624 | =item ExtractEmbedded
|
---|
625 |
|
---|
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.
|
---|
632 |
|
---|
633 | =item FastScan
|
---|
634 |
|
---|
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
|
---|
644 | combined with the ScanForXMP option, prevents scanning for XMP in recognized
|
---|
645 | file types. With a value of 2, ExifTool will also avoid extracting any EXIF
|
---|
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.
|
---|
670 |
|
---|
671 | =item FixBase
|
---|
672 |
|
---|
673 | Fix maker notes base offset. A common problem with image editing software
|
---|
674 | is that offsets in the maker notes are not adjusted properly when the file
|
---|
675 | is modified. This may cause the wrong values to be extracted for some maker
|
---|
676 | note entries when reading the edited file. FixBase specifies an integer
|
---|
677 | value to be added to the maker notes base offset. It may also be set to the
|
---|
678 | empty string ('') for ExifTool will take its best guess at the correct base,
|
---|
679 | or undef (the default) for no base adjustment.
|
---|
680 |
|
---|
681 | =item GeoMaxIntSecs
|
---|
682 |
|
---|
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.
|
---|
690 |
|
---|
691 | =item GeoMaxExtSecs
|
---|
692 |
|
---|
693 | Maximum extrapolation time in seconds for geotagging. Geotagging fails if
|
---|
694 | the Geotime value lies outside a GPS track by a number of seconds greater
|
---|
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.
|
---|
698 |
|
---|
699 | =item GeoMaxHDOP
|
---|
700 |
|
---|
701 | Maximum Horizontal (2D) Dilution Of Precision for geotagging. GPS fixes are
|
---|
702 | ignored if the HDOP is greater than this. Default is undef.
|
---|
703 |
|
---|
704 | =item GeoMaxPDOP
|
---|
705 |
|
---|
706 | Maximum Position (3D) Dilution Of Precision for geotagging. GPS fixes are
|
---|
707 | ignored if the PDOP is greater than this. Default is undef.
|
---|
708 |
|
---|
709 | =item GeoMinSats
|
---|
710 |
|
---|
711 | Minimum number of satellites for geotagging. GPS fixes are ignored if the
|
---|
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.
|
---|
728 |
|
---|
729 | =item Group#
|
---|
730 |
|
---|
731 | Extract tags only for specified groups in family # (Group0 assumed if #
|
---|
732 | not given). The option value may be a single group name or a reference
|
---|
733 | to a list of groups. Case is significant in group names. Specify a group
|
---|
734 | to be excluded by preceding group name with a '-'. See L</GetGroup> for a
|
---|
735 | description of group families, and L</GetAllGroups [static]> for lists of
|
---|
736 | group names.
|
---|
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 |
|
---|
743 | =item HtmlDump
|
---|
744 |
|
---|
745 | Dump information in hex to dynamic HTML web page. The value may be 0-3 for
|
---|
746 | increasingly larger limits on the maximum block size. Default is 0. Output
|
---|
747 | goes to the file specified by the TextOut option (\*STDOUT by default).
|
---|
748 |
|
---|
749 | =item HtmlDumpBase
|
---|
750 |
|
---|
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.
|
---|
753 |
|
---|
754 | =item IgnoreMinorErrors
|
---|
755 |
|
---|
756 | Flag to ignore minor errors. Causes minor errors to be downgraded to
|
---|
757 | warnings, and minor warnings to be ignored. This option is provided mainly
|
---|
758 | to allow writing of files when minor errors occur, but by ignoring some
|
---|
759 | minor warnings the behaviour of ExifTool may be changed to allow some
|
---|
760 | questionable operations to proceed (such as extracting thumbnail and preview
|
---|
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.
|
---|
764 |
|
---|
765 | =item Lang
|
---|
766 |
|
---|
767 | Localized language for exiftool tag descriptions, etc. Available languages
|
---|
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'.
|
---|
771 |
|
---|
772 | =item LargeFileSupport
|
---|
773 |
|
---|
774 | Flag to indicate that 64-bit file offsets are supported on this system.
|
---|
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 ', '.
|
---|
790 |
|
---|
791 | =item ListSplit
|
---|
792 |
|
---|
793 | Regular expression used to split values of list-type tags into individual
|
---|
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.
|
---|
796 |
|
---|
797 | =item MakerNotes
|
---|
798 |
|
---|
799 | Option to extract MakerNotes and other writable subdirectories (such as
|
---|
800 | PrintIM) as a data block. Normally when the MakerNotes are extracted they
|
---|
801 | are rebuilt to include data outside the boundaries of the original maker
|
---|
802 | note data block, but a value of 2 disables this feature. Possible values
|
---|
803 | are:
|
---|
804 |
|
---|
805 | 0 - Do not extract writable subdirectories (same as default of undef)
|
---|
806 | 1 - Extract and rebuild maker notes into self-contained block
|
---|
807 | 2 - Extract without rebuilding maker notes
|
---|
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 |
|
---|
814 | =item MissingTagValue
|
---|
815 |
|
---|
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.
|
---|
830 |
|
---|
831 | =item Password
|
---|
832 |
|
---|
833 | Password for reading/writing password-protected PDF documents. Ignored if a
|
---|
834 | password is not required. Character encoding of the password is determined
|
---|
835 | by the value of the Charset option at processing time. Default is undef.
|
---|
836 |
|
---|
837 | =item PrintConv
|
---|
838 |
|
---|
839 | Flag to enable automatic print conversion. Also enables inverse
|
---|
840 | print conversion for writing. Default is 1.
|
---|
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 |
|
---|
893 | =item ScanForXMP
|
---|
894 |
|
---|
895 | Flag to scan all files (even unrecognized formats) for XMP information
|
---|
896 | unless XMP was already found in the file. When combined with the FastScan
|
---|
897 | option, only unrecognized file types are scanned for XMP. Default is undef.
|
---|
898 |
|
---|
899 | =item Sort
|
---|
900 |
|
---|
901 | Specifies order to sort tags in returned list:
|
---|
902 |
|
---|
903 | Input - Sort in same order as input tag arguments (default)
|
---|
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)
|
---|
907 | Group# - Sort by tag group, where # is zero or more family
|
---|
908 | numbers separated by colons. If # is not specified,
|
---|
909 | Group0 is assumed. See GetGroup for a description
|
---|
910 | of group families.
|
---|
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 |
|
---|
920 | =item StrictDate
|
---|
921 |
|
---|
922 | Flag to return undefined value for any date which can't be converted when
|
---|
923 | the DateFormat option is used. Default is undef.
|
---|
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 |
|
---|
939 | =item Struct
|
---|
940 |
|
---|
941 | Flag to return XMP structures as hash references instead of flattening into
|
---|
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.
|
---|
956 |
|
---|
957 | =item TextOut
|
---|
958 |
|
---|
959 | Output file reference for Verbose and HtmlDump options. Default is
|
---|
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.)
|
---|
968 |
|
---|
969 | =item Unknown
|
---|
970 |
|
---|
971 | Flag to get the values of unknown tags. If set to 1, unknown tags are
|
---|
972 | extracted from EXIF (or other tagged-format) directories. If set to 2,
|
---|
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.
|
---|
1002 |
|
---|
1003 | =item Verbose
|
---|
1004 |
|
---|
1005 | Print verbose messages to file specified by TextOut option. Value may be
|
---|
1006 | from 0 to 5 for increasingly verbose messages. Default is 0. With the
|
---|
1007 | verbose option set, messages are printed to the console as the file is
|
---|
1008 | parsed. Level 1 prints the tag names and raw values. Level 2 adds more
|
---|
1009 | details about the tags. Level 3 adds a hex dump of the tag data, but with
|
---|
1010 | limits on the number of bytes dumped. Levels 4 and 5 remove the dump limit
|
---|
1011 | on tag values and JPEG segment data respectively.
|
---|
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 |
|
---|
1038 | =back
|
---|
1039 |
|
---|
1040 | =item Return Values:
|
---|
1041 |
|
---|
1042 | The original value of the last specified parameter.
|
---|
1043 |
|
---|
1044 | =back
|
---|
1045 |
|
---|
1046 | =head2 ClearOptions
|
---|
1047 |
|
---|
1048 | Reset all options to their default values. Loads user-defined default
|
---|
1049 | option values from the %Image::ExifTool::UserDefined::Options hash in the
|
---|
1050 | .ExifTool_config file if it exists.
|
---|
1051 |
|
---|
1052 | $exifTool->ClearOptions();
|
---|
1053 |
|
---|
1054 | =over 4
|
---|
1055 |
|
---|
1056 | =item Inputs:
|
---|
1057 |
|
---|
1058 | 0) ExifTool object reference
|
---|
1059 |
|
---|
1060 | =item Return Values:
|
---|
1061 |
|
---|
1062 | (none)
|
---|
1063 |
|
---|
1064 | =back
|
---|
1065 |
|
---|
1066 | =head2 ExtractInfo
|
---|
1067 |
|
---|
1068 | Extract all meta information from an image.
|
---|
1069 |
|
---|
1070 | $success = $exifTool->ExtractInfo('image.jpg', \%options);
|
---|
1071 |
|
---|
1072 | =over 4
|
---|
1073 |
|
---|
1074 | =item Inputs:
|
---|
1075 |
|
---|
1076 | L</ExtractInfo> takes exactly the same arguments as L</ImageInfo>. The only
|
---|
1077 | difference is that a list of tag keys is not returned if an ARRAY reference
|
---|
1078 | is given. The following options are effective in the call to
|
---|
1079 | L</ExtractInfo>:
|
---|
1080 |
|
---|
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.
|
---|
1088 |
|
---|
1089 | =item Return Value:
|
---|
1090 |
|
---|
1091 | 1 if this was a recognized file format, 0 otherwise (and 'Error' tag set).
|
---|
1092 |
|
---|
1093 | =back
|
---|
1094 |
|
---|
1095 | =head2 GetInfo
|
---|
1096 |
|
---|
1097 | L</GetInfo> is called to return meta information after it has been extracted
|
---|
1098 | from the image by a previous call to L</ExtractInfo> or L</ImageInfo>. This
|
---|
1099 | function may be called repeatedly after a single call to L</ExtractInfo> or
|
---|
1100 | L</ImageInfo>.
|
---|
1101 |
|
---|
1102 | # get image width and height only
|
---|
1103 | $info = $exifTool->GetInfo('ImageWidth', 'ImageHeight');
|
---|
1104 |
|
---|
1105 | # get all Error and Warning messages
|
---|
1106 | $info = $exifTool->GetInfo('Error', 'Warning');
|
---|
1107 |
|
---|
1108 | # get information for all tags in list (list updated with tags found)
|
---|
1109 | $info = $exifTool->GetInfo(\@ioTagList);
|
---|
1110 |
|
---|
1111 | # get all information in Author or Location groups
|
---|
1112 | $info = $exifTool->GetInfo({Group2 => ['Author', 'Location']});
|
---|
1113 |
|
---|
1114 | =over 4
|
---|
1115 |
|
---|
1116 | =item Inputs:
|
---|
1117 |
|
---|
1118 | Inputs are the same as L</ExtractInfo> and L</ImageInfo> except that an
|
---|
1119 | image can not be specified. Options in effect are:
|
---|
1120 |
|
---|
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
|
---|
1136 | StrictDate.
|
---|
1137 |
|
---|
1138 | =head2 WriteInfo
|
---|
1139 |
|
---|
1140 | Write meta information to a file. The specified source file is rewritten to
|
---|
1141 | the same-type destination file with new information as specified by previous
|
---|
1142 | calls to L</SetNewValue>. The necessary segments and/or directories are
|
---|
1143 | created in the destination file as required to store the specified
|
---|
1144 | information. May be called repeatedly to write the same information to
|
---|
1145 | additional files without the need to call L</SetNewValue> again.
|
---|
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 |
|
---|
1158 | # add information to a source file, writing output to new file
|
---|
1159 | $exifTool->WriteInfo($srcfile, $dstfile);
|
---|
1160 |
|
---|
1161 | # create XMP data file from scratch
|
---|
1162 | $exifTool->WriteInfo(undef, $dstfile, 'XMP');
|
---|
1163 |
|
---|
1164 | # overwrite file (you do have backups, right?)
|
---|
1165 | $exifTool->WriteInfo($srcfile);
|
---|
1166 |
|
---|
1167 | =over 4
|
---|
1168 |
|
---|
1169 | =item Inputs:
|
---|
1170 |
|
---|
1171 | 0) ExifTool object reference
|
---|
1172 |
|
---|
1173 | 1) Source file name, file reference, scalar reference, or undef to create a
|
---|
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.
|
---|
1177 |
|
---|
1178 | 2) [optional] Destination file name, file reference, scalar reference, or
|
---|
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.
|
---|
1182 |
|
---|
1183 | =item Return Value:
|
---|
1184 |
|
---|
1185 | 1 if file was written OK, 2 if file was written but no changes made, 0 on
|
---|
1186 | file write error.
|
---|
1187 |
|
---|
1188 | If an error code is returned, an Error tag is set and GetValue('Error') can
|
---|
1189 | be called to obtain the error description. A Warning tag may be set even if
|
---|
1190 | this routine is successful. Calling WriteInfo clears any pre-existing Error
|
---|
1191 | and Warning tags.
|
---|
1192 |
|
---|
1193 | $errorMessage = $exifTool->GetValue('Error');
|
---|
1194 | $warningMessage = $exifTool->GetValue('Warning');
|
---|
1195 |
|
---|
1196 | =item Notes:
|
---|
1197 |
|
---|
1198 | The source file name may be undefined to create a file from scratch
|
---|
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.
|
---|
1203 |
|
---|
1204 | If a destination file name is given, the specified file must not exist
|
---|
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.
|
---|
1215 |
|
---|
1216 | On Mac OS systems, the file resource fork is preserved if this routine is
|
---|
1217 | called with a source file name.
|
---|
1218 |
|
---|
1219 | =back
|
---|
1220 |
|
---|
1221 | The following ExifTool options are effective in the call to L</WriteInfo>:
|
---|
1222 |
|
---|
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');
|
---|
1232 |
|
---|
1233 | =over 4
|
---|
1234 |
|
---|
1235 | =item Inputs:
|
---|
1236 |
|
---|
1237 | 0) ExifTool object reference
|
---|
1238 |
|
---|
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')
|
---|
1244 |
|
---|
1245 | If the information hash or tag list reference is not provided, then the list
|
---|
1246 | of found tags from the last call to L</ImageInfo>, L</ExtractInfo> or
|
---|
1247 | L</GetInfo> is used instead, and the result is the same as if
|
---|
1248 | L</GetFoundTags> was called. If sort order is not specified, the sort order
|
---|
1249 | is taken from the current options settings.
|
---|
1250 |
|
---|
1251 | =item Return Values:
|
---|
1252 |
|
---|
1253 | A list of tag keys in the specified order.
|
---|
1254 |
|
---|
1255 | =back
|
---|
1256 |
|
---|
1257 | =head2 GetFoundTags
|
---|
1258 |
|
---|
1259 | Get list of found tags in specified sort order. The found tags are the tags
|
---|
1260 | for the information obtained from the most recent call to L</ImageInfo>,
|
---|
1261 | L</ExtractInfo> or L</GetInfo> for this object.
|
---|
1262 |
|
---|
1263 | @tags = $exifTool->GetFoundTags('File');
|
---|
1264 |
|
---|
1265 | =over 4
|
---|
1266 |
|
---|
1267 | =item Inputs:
|
---|
1268 |
|
---|
1269 | 0) ExifTool object reference
|
---|
1270 |
|
---|
1271 | 1) [optional] Sort order ('Input', 'File', 'Tag', 'Descr' or 'Group#')
|
---|
1272 |
|
---|
1273 | 2) [optional] Secondary sort order ('File', 'Tag' or 'Descr')
|
---|
1274 |
|
---|
1275 | If sort order is not specified, the sort order from the ExifTool options is
|
---|
1276 | used.
|
---|
1277 |
|
---|
1278 | =item Return Values:
|
---|
1279 |
|
---|
1280 | A list of tag keys in the specified order.
|
---|
1281 |
|
---|
1282 | =back
|
---|
1283 |
|
---|
1284 | =head2 GetRequestedTags
|
---|
1285 |
|
---|
1286 | Get list of requested tags. These are the tags that were specified in the
|
---|
1287 | arguments of the most recent call to L</ImageInfo>, L</ExtractInfo> or
|
---|
1288 | L</GetInfo>, including tags specified via a tag list reference. Shortcut
|
---|
1289 | tags are expanded in the list.
|
---|
1290 |
|
---|
1291 | @tags = $exifTool->GetRequestedTags();
|
---|
1292 |
|
---|
1293 | =over 4
|
---|
1294 |
|
---|
1295 | =item Inputs:
|
---|
1296 |
|
---|
1297 | (none)
|
---|
1298 |
|
---|
1299 | =item Return Values:
|
---|
1300 |
|
---|
1301 | List of requested tag keys in the same order that the tags were specified.
|
---|
1302 | Note that this list will be empty if tags were not specifically requested
|
---|
1303 | (ie. If extracting all tags).
|
---|
1304 |
|
---|
1305 | =back
|
---|
1306 |
|
---|
1307 | =head2 GetValue
|
---|
1308 |
|
---|
1309 | Get the value of a specified tag. The returned value is either the
|
---|
1310 | human-readable (PrintConv) value, the converted machine-readable (ValueConv)
|
---|
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.
|
---|
1317 |
|
---|
1318 | Tags which represent lists of multiple values (as may happen with 'Keywords'
|
---|
1319 | for example) are handled specially. In scalar context, the returned
|
---|
1320 | PrintConv value for these tags is either a string of values or a list
|
---|
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.
|
---|
1324 |
|
---|
1325 | Note that L</GetValue> requires a case-sensitive tag key as an argument. To
|
---|
1326 | retrieve tag information based on a case-insensitive tag name (with an
|
---|
1327 | optional group specifier), use L</GetInfo> instead.
|
---|
1328 |
|
---|
1329 | # PrintConv example
|
---|
1330 | my $val = $exifTool->GetValue($tag);
|
---|
1331 | if (ref $val eq 'SCALAR') {
|
---|
1332 | print "$tag = (unprintable value)\n";
|
---|
1333 | } else {
|
---|
1334 | print "$tag = $val\n";
|
---|
1335 | }
|
---|
1336 |
|
---|
1337 | # ValueConv examples
|
---|
1338 | my $val = $exifTool->GetValue($tag, 'ValueConv');
|
---|
1339 | if (ref $val eq 'ARRAY') {
|
---|
1340 | print "$tag is a list of values\n";
|
---|
1341 | } elsif (ref $val eq 'SCALAR') {
|
---|
1342 | print "$tag represents binary data\n";
|
---|
1343 | } else {
|
---|
1344 | print "$tag is a simple scalar\n";
|
---|
1345 | }
|
---|
1346 |
|
---|
1347 | my @keywords = $exifTool->GetValue('Keywords', 'ValueConv');
|
---|
1348 |
|
---|
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.
|
---|
1354 |
|
---|
1355 | =over 4
|
---|
1356 |
|
---|
1357 | =item Inputs:
|
---|
1358 |
|
---|
1359 | 0) ExifTool object reference
|
---|
1360 |
|
---|
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'
|
---|
1365 |
|
---|
1366 | The default value type is 'PrintConv' if the PrintConv option is set,
|
---|
1367 | otherwise the default is 'ValueConv'. A value type of 'Both' returns both
|
---|
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.
|
---|
1371 |
|
---|
1372 | =item Return Values:
|
---|
1373 |
|
---|
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.
|
---|
1381 |
|
---|
1382 | Note: It is possible for L</GetValue> to return an undefined ValueConv or
|
---|
1383 | PrintConv value (or an empty list in list context) even if the tag exists,
|
---|
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.
|
---|
1387 |
|
---|
1388 | =back
|
---|
1389 |
|
---|
1390 | =head2 SetNewValue
|
---|
1391 |
|
---|
1392 | Set the new value for a tag. The routine may be called multiple times to
|
---|
1393 | set the values of many tags before using L</WriteInfo> to write the new
|
---|
1394 | values to an image.
|
---|
1395 |
|
---|
1396 | For list-type tags (like Keywords), either call repeatedly with the same tag
|
---|
1397 | name for each value, or call with a reference to the list of values.
|
---|
1398 |
|
---|
1399 | # set a new value for a tag (errors go to STDERR)
|
---|
1400 | $success = $exifTool->SetNewValue($tag, $value);
|
---|
1401 |
|
---|
1402 | # set a new value and capture any error message
|
---|
1403 | ($success, $errStr) = $exifTool->SetNewValue($tag, $value);
|
---|
1404 |
|
---|
1405 | # delete information for specified tag if it exists in image
|
---|
1406 | # (also resets AddValue and DelValue options for this tag)
|
---|
1407 | $exifTool->SetNewValue($tag);
|
---|
1408 |
|
---|
1409 | # reset all values from previous calls to SetNewValue()
|
---|
1410 | $exifTool->SetNewValue();
|
---|
1411 |
|
---|
1412 | # delete a specific keyword
|
---|
1413 | $exifTool->SetNewValue('Keywords', $word, DelValue => 1);
|
---|
1414 |
|
---|
1415 | # set keywords (a list-type tag) with two new values
|
---|
1416 | $exifTool->SetNewValue(Keywords => 'word1');
|
---|
1417 | $exifTool->SetNewValue(Keywords => 'word2');
|
---|
1418 | # equivalent, but set both in one call using an array reference
|
---|
1419 | $exifTool->SetNewValue(Keywords => ['word1','word2']);
|
---|
1420 |
|
---|
1421 | # add a keyword without replacing existing keywords in the file
|
---|
1422 | $exifTool->SetNewValue(Keywords => $word, AddValue => 1);
|
---|
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 |
|
---|
1430 | # set a tag in a specific group
|
---|
1431 | $exifTool->SetNewValue(Headline => $val, Group => 'XMP');
|
---|
1432 | $exifTool->SetNewValue('XMP:Headline' => $val); # (equivalent)
|
---|
1433 |
|
---|
1434 | # shift original date/time back by 2.5 hours
|
---|
1435 | $exifTool->SetNewValue(DateTimeOriginal => '2:30', Shift => -1);
|
---|
1436 |
|
---|
1437 | # write a tag only if it had a specific value
|
---|
1438 | # (the order of the following calls is not significant)
|
---|
1439 | $exifTool->SetNewValue(Title => $oldVal, DelValue => 1);
|
---|
1440 | $exifTool->SetNewValue(Title => $newVal);
|
---|
1441 |
|
---|
1442 | # write tag by numerical value
|
---|
1443 | $exifTool->SetNewValue(Orientation => 6, Type => 'ValueConv');
|
---|
1444 | $exifTool->SetNewValue('Orientation#' => 6); # (equivalent)
|
---|
1445 |
|
---|
1446 | # delete all but EXIF tags
|
---|
1447 | $exifTool->SetNewValue('*'); # delete all...
|
---|
1448 | $exifTool->SetNewValue('EXIF:*', undef, Replace => 2); # ...but EXIF
|
---|
1449 |
|
---|
1450 | # write structured information as a HASH reference
|
---|
1451 | $exifTool->SetNewValue('XMP:Flash' => {
|
---|
1452 | mode => 'on',
|
---|
1453 | fired => 'true',
|
---|
1454 | return => 'not'
|
---|
1455 | });
|
---|
1456 |
|
---|
1457 | # write structured information as a serialized string
|
---|
1458 | $exifTool->SetNewValue('XMP:Flash'=>'{mode=on,fired=true,return=not}');
|
---|
1459 |
|
---|
1460 | (See L<https://exiftool.org/struct.html#Serialize> for a description of the
|
---|
1461 | structure serialization technique.)
|
---|
1462 |
|
---|
1463 | =over 4
|
---|
1464 |
|
---|
1465 | =item Inputs:
|
---|
1466 |
|
---|
1467 | 0) ExifTool object reference
|
---|
1468 |
|
---|
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.
|
---|
1482 |
|
---|
1483 | 2) [optional] New value for tag. Undefined to delete tag from file. May be
|
---|
1484 | a scalar, scalar reference, list reference to set a list of values, or hash
|
---|
1485 | reference for a structure. Integer values may be specified as a hexadecimal
|
---|
1486 | string (with a leading '0x'), and simple rational values may be specified in
|
---|
1487 | fractional form (eg. '4/10'). Structure tags may be specified either as a
|
---|
1488 | hash reference or a serialized string (see the last two examples above).
|
---|
1489 |
|
---|
1490 | 3-N) [optional] SetNewValue option/value pairs (see below).
|
---|
1491 |
|
---|
1492 | =item SetNewValue Options:
|
---|
1493 |
|
---|
1494 | =over 4
|
---|
1495 |
|
---|
1496 | =item AddValue
|
---|
1497 |
|
---|
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.
|
---|
1502 |
|
---|
1503 | =item DelValue
|
---|
1504 |
|
---|
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.
|
---|
1512 |
|
---|
1513 | =item EditGroup
|
---|
1514 |
|
---|
1515 | Create tags in existing groups only. Don't create new group. Valid values
|
---|
1516 | are 0 and 1. Effectively removes the 'g' from the ExifTool WriteMode option
|
---|
1517 | for this tag only. Default is 0.
|
---|
1518 |
|
---|
1519 | =item EditOnly
|
---|
1520 |
|
---|
1521 | Edit tag only if it already exists. Don't create new tag. Valid values are
|
---|
1522 | 0 and 1. Effectively removes the 'c' from the ExifTool WriteMode option for
|
---|
1523 | this tag only. Default is 0.
|
---|
1524 |
|
---|
1525 | =item Group
|
---|
1526 |
|
---|
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'.
|
---|
1536 |
|
---|
1537 | =item NoShortcut
|
---|
1538 |
|
---|
1539 | Disables default behaviour of looking up tag in shortcuts if not found
|
---|
1540 | otherwise.
|
---|
1541 |
|
---|
1542 | =item Protected
|
---|
1543 |
|
---|
1544 | Bit mask for tag protection levels to write. Bit 0x01 allows writing of
|
---|
1545 | 'unsafe' tags (ie. tags not copied automatically via
|
---|
1546 | L</SetNewValuesFromFile>). Bit 0x02 allows writing of 'protected' tags, and
|
---|
1547 | should only be used internally by ExifTool. See
|
---|
1548 | L<Image::ExifTool::TagNames|Image::ExifTool::TagNames>, for a list of tag
|
---|
1549 | names indicating 'unsafe' and 'protected' tags. Default is 0.
|
---|
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 |
|
---|
1557 | =item Replace
|
---|
1558 |
|
---|
1559 | Flag to replace the previous new values for this tag (ie. replace the values
|
---|
1560 | set in previous calls to L</SetNewValue>). This option is most commonly
|
---|
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.
|
---|
1565 |
|
---|
1566 | =item Shift
|
---|
1567 |
|
---|
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.
|
---|
1575 |
|
---|
1576 | =item Type
|
---|
1577 |
|
---|
1578 | The type of value being set. Valid values are PrintConv, ValueConv or Raw.
|
---|
1579 | Default is PrintConv if the L</PrintConv> Option is set, otherwise
|
---|
1580 | ValueConv.
|
---|
1581 |
|
---|
1582 | =back
|
---|
1583 |
|
---|
1584 | =item Return Values:
|
---|
1585 |
|
---|
1586 | In scalar context, returns the number of tags set and error messages are
|
---|
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).
|
---|
1589 |
|
---|
1590 | =item Notes:
|
---|
1591 |
|
---|
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').
|
---|
1602 |
|
---|
1603 | =back
|
---|
1604 |
|
---|
1605 | The following ExifTool options are effective in the call to L</SetNewValue>:
|
---|
1606 |
|
---|
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
|
---|
1636 |
|
---|
1637 | =head2 SetNewValuesFromFile
|
---|
1638 |
|
---|
1639 | A very powerful routine that sets new values for tags from information found
|
---|
1640 | in a specified file.
|
---|
1641 |
|
---|
1642 | # set new values from all information in a file...
|
---|
1643 | my $info = $exifTool->SetNewValuesFromFile($srcFile);
|
---|
1644 | # ...then write these values to another image
|
---|
1645 | my $result = $exifTool->WriteInfo($file2, $outFile);
|
---|
1646 |
|
---|
1647 | # set all new values, preserving original groups
|
---|
1648 | $exifTool->SetNewValuesFromFile($srcFile, '*:*');
|
---|
1649 |
|
---|
1650 | # set specific information
|
---|
1651 | $exifTool->SetNewValuesFromFile($srcFile, @tags);
|
---|
1652 |
|
---|
1653 | # set new value from a different tag in specific group
|
---|
1654 | $exifTool->SetNewValuesFromFile($fp, 'XMP-dc:Subject<IPTC:Keywords');
|
---|
1655 |
|
---|
1656 | # add all IPTC keywords to XMP subject list
|
---|
1657 | $exifTool->SetNewValuesFromFile($fp, 'XMP-dc:Subject+<IPTC:Keywords');
|
---|
1658 |
|
---|
1659 | # set new value from an expression involving other tags
|
---|
1660 | $exifTool->SetNewValuesFromFile($file,
|
---|
1661 | 'Comment<ISO=$ISO Aperture=$aperture Exposure=$shutterSpeed');
|
---|
1662 |
|
---|
1663 | # set keywords list from the values of multiple tags
|
---|
1664 | $exifTool->SetNewValuesFromFile($file, { Replace => 0 },
|
---|
1665 | 'keywords<xmp:subject', 'keywords<filename');
|
---|
1666 |
|
---|
1667 | # copy all EXIF information, preserving the original IFD
|
---|
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');
|
---|
1678 |
|
---|
1679 | =over 4
|
---|
1680 |
|
---|
1681 | =item Inputs:
|
---|
1682 |
|
---|
1683 | 0) ExifTool object reference
|
---|
1684 |
|
---|
1685 | 1) File name, file reference, or scalar reference
|
---|
1686 |
|
---|
1687 | 2-N) [optional] List of tag names to set or options hash references. All
|
---|
1688 | writable tags are set if none are specified. The tag names are not case
|
---|
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.
|
---|
1718 |
|
---|
1719 | By default, this routine will commute information between same-named tags in
|
---|
1720 | different groups, allowing information to be translated between images with
|
---|
1721 | different formats. This behaviour may be modified by specifying a group
|
---|
1722 | name for extracted tags (even if '*' is used as a group name), in which case
|
---|
1723 | the information is written to the original group, unless redirected to a
|
---|
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.)
|
---|
1729 |
|
---|
1730 | =item SetNewValuesFromFile Options:
|
---|
1731 |
|
---|
1732 | The options are the same was for L</SetNewValue>, and are passed directly
|
---|
1733 | to L</SetNewValue> internally, with a few exceptions:
|
---|
1734 |
|
---|
1735 | - The Replace option defaults to 1 instead of 0 as with L</SetNewValue>.
|
---|
1736 |
|
---|
1737 | - The AddValue or DelValue option is set for individual tags if '+>' or '->'
|
---|
1738 | (or '+E<lt>' or '-E<lt>') are used.
|
---|
1739 |
|
---|
1740 | - The Group option is set for tags where a group name is given.
|
---|
1741 |
|
---|
1742 | - The Protected flag is set to 1 for individually specified tags.
|
---|
1743 |
|
---|
1744 | - The Type option also applies to extracted tags.
|
---|
1745 |
|
---|
1746 | =item Return Values:
|
---|
1747 |
|
---|
1748 | A hash of information that was set successfully. May include Warning or
|
---|
1749 | Error entries if there were problems reading the input file.
|
---|
1750 |
|
---|
1751 | =item Notes:
|
---|
1752 |
|
---|
1753 | The PrintConv option applies to this routine, but it normally should be left
|
---|
1754 | on to provide more reliable transfer of information between groups.
|
---|
1755 |
|
---|
1756 | If a preview image exists, it is not copied. The preview image must be
|
---|
1757 | transferred separately if desired, in a separate call to L</WriteInfo>
|
---|
1758 |
|
---|
1759 | When simply copying all information between files of the same type, it is
|
---|
1760 | usually desirable to preserve the original groups by specifying '*:*' for
|
---|
1761 | the tags to set.
|
---|
1762 |
|
---|
1763 | The L</Duplicates> option is always in effect for tags extracted from the
|
---|
1764 | source file using this routine.
|
---|
1765 |
|
---|
1766 | The L</Struct> option is enabled by default for tags extracted by this
|
---|
1767 | routine. This allows the hierarchy of complex structures to be preserved
|
---|
1768 | when copying, but the Struct option may be set to 0 to override this
|
---|
1769 | behaviour and copy as flattened tags instead.
|
---|
1770 |
|
---|
1771 | =back
|
---|
1772 |
|
---|
1773 | =head2 CountNewValues
|
---|
1774 |
|
---|
1775 | Return the total number of new values set.
|
---|
1776 |
|
---|
1777 | $numSet = $exifTool->CountNewValues();
|
---|
1778 | ($numSet, $numPseudo) = $exifTool->CountNewValues();
|
---|
1779 |
|
---|
1780 | =over 4
|
---|
1781 |
|
---|
1782 | =item Inputs:
|
---|
1783 |
|
---|
1784 | 0) ExifTool object reference
|
---|
1785 |
|
---|
1786 | =item Return Values:
|
---|
1787 |
|
---|
1788 | In scalar context, returns the total number of tags with new values set. In
|
---|
1789 | list context, also returns the number of "pseudo" tag values which have been
|
---|
1790 | set. "Pseudo" tags are tags like FileName and FileModifyDate which are not
|
---|
1791 | contained within the file and can be changed without rewriting the file.
|
---|
1792 |
|
---|
1793 | =back
|
---|
1794 |
|
---|
1795 | =head2 SaveNewValues
|
---|
1796 |
|
---|
1797 | Save state of new values to be later restored by L</RestoreNewValues>.
|
---|
1798 |
|
---|
1799 | $exifTool->SaveNewValues(); # save state of new values
|
---|
1800 | $exifTool->SetNewValue(ISO => 100); # set new value for ISO
|
---|
1801 | $exifTool->WriteInfo($src, $dst1); # write ISO + previous new values
|
---|
1802 | $exifTool->RestoreNewValues(); # restore previous new values
|
---|
1803 | $exifTool->WriteInfo($src, $dst2); # write previous new values only
|
---|
1804 |
|
---|
1805 | =over 4
|
---|
1806 |
|
---|
1807 | =item Inputs:
|
---|
1808 |
|
---|
1809 | 0) ExifTool object reference
|
---|
1810 |
|
---|
1811 | =item Return Value:
|
---|
1812 |
|
---|
1813 | Count of the number of times this routine has been called (N) since the last
|
---|
1814 | time the new values were reset.
|
---|
1815 |
|
---|
1816 | =back
|
---|
1817 |
|
---|
1818 | =head2 RestoreNewValues
|
---|
1819 |
|
---|
1820 | Restore new values to the settings that existed when L</SaveNewValues> was
|
---|
1821 | last called. May be called repeatedly after a single call to
|
---|
1822 | L</SaveNewValues>. See L</SaveNewValues> above for an example.
|
---|
1823 |
|
---|
1824 | =over 4
|
---|
1825 |
|
---|
1826 | =item Inputs:
|
---|
1827 |
|
---|
1828 | 0) ExifTool object reference
|
---|
1829 |
|
---|
1830 | =item Return Value:
|
---|
1831 |
|
---|
1832 | None.
|
---|
1833 |
|
---|
1834 | =back
|
---|
1835 |
|
---|
1836 | =head2 SetFileModifyDate
|
---|
1837 |
|
---|
1838 | Write the filesystem modification or creation time from the new value of the
|
---|
1839 | FileModifyDate or FileCreateDate tag.
|
---|
1840 |
|
---|
1841 | $exifTool->SetNewValue(FileModifyDate => '2000:01:02 03:04:05-05:00',
|
---|
1842 | Protected => 1);
|
---|
1843 | $result = $exifTool->SetFileModifyDate($file);
|
---|
1844 |
|
---|
1845 | =over 4
|
---|
1846 |
|
---|
1847 | =item Inputs:
|
---|
1848 |
|
---|
1849 | 0) ExifTool object reference
|
---|
1850 |
|
---|
1851 | 1) File name
|
---|
1852 |
|
---|
1853 | 2) [optional] Base time if applying shift (days before $^T)
|
---|
1854 |
|
---|
1855 | 3) [optional] Tag to write: 'FileModifyDate' (default), or 'FileCreateDate'
|
---|
1856 |
|
---|
1857 | =item Return Value:
|
---|
1858 |
|
---|
1859 | 1 if the time was changed, 0 if nothing was done, or -1 if there was an
|
---|
1860 | error setting the time.
|
---|
1861 |
|
---|
1862 | =item Notes:
|
---|
1863 |
|
---|
1864 | Equivalent to, but more efficient than calling L</WriteInfo> when only the
|
---|
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.
|
---|
1871 |
|
---|
1872 | =back
|
---|
1873 |
|
---|
1874 | =head2 SetFileName
|
---|
1875 |
|
---|
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.
|
---|
1883 |
|
---|
1884 | $result = $exifTool->SetFileName($file);
|
---|
1885 | $result = $exifTool->SetFileName($file, $newName);
|
---|
1886 |
|
---|
1887 | =over 4
|
---|
1888 |
|
---|
1889 | =item Inputs:
|
---|
1890 |
|
---|
1891 | 0) ExifTool object reference
|
---|
1892 |
|
---|
1893 | 1) Current file name
|
---|
1894 |
|
---|
1895 | 2) [optional] New file name
|
---|
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 |
|
---|
1901 | =item Return Value:
|
---|
1902 |
|
---|
1903 | 1 on success, 0 if nothing was done, or -1 if there was an error renaming the
|
---|
1904 | file or creating the link.
|
---|
1905 |
|
---|
1906 | =item Notes:
|
---|
1907 |
|
---|
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}>.
|
---|
1911 |
|
---|
1912 | =back
|
---|
1913 |
|
---|
1914 | =head2 SetNewGroups
|
---|
1915 |
|
---|
1916 | Set the order of the preferred groups when adding new information. In
|
---|
1917 | subsequent calls to L</SetNewValue>, new information will be created in the
|
---|
1918 | first valid group of this list. This has an impact only if the group is not
|
---|
1919 | specified when calling L</SetNewValue> and if the tag name exists in more
|
---|
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.
|
---|
1923 |
|
---|
1924 | $exifTool->SetNewGroups('XMP','EXIF','IPTC');
|
---|
1925 |
|
---|
1926 | =over 4
|
---|
1927 |
|
---|
1928 | =item Inputs:
|
---|
1929 |
|
---|
1930 | 0) ExifTool object reference
|
---|
1931 |
|
---|
1932 | 1-N) Groups in order of priority. If no groups are specified, the priorities
|
---|
1933 | are reset to the defaults.
|
---|
1934 |
|
---|
1935 | =item Return Value:
|
---|
1936 |
|
---|
1937 | None.
|
---|
1938 |
|
---|
1939 | =back
|
---|
1940 |
|
---|
1941 | =head2 GetNewGroups
|
---|
1942 |
|
---|
1943 | Get current group priority list.
|
---|
1944 |
|
---|
1945 | @groups = $exifTool->GetNewGroups();
|
---|
1946 |
|
---|
1947 | =over 4
|
---|
1948 |
|
---|
1949 | =item Inputs:
|
---|
1950 |
|
---|
1951 | 0) ExifTool object reference
|
---|
1952 |
|
---|
1953 | =item Return Values:
|
---|
1954 |
|
---|
1955 | List of group names in order of write priority. Highest priority first.
|
---|
1956 |
|
---|
1957 | =back
|
---|
1958 |
|
---|
1959 | =head2 GetTagID
|
---|
1960 |
|
---|
1961 | Get the ID for the specified tag. The ID is the IFD tag number in EXIF
|
---|
1962 | information, the property name in XMP information, or the data offset in a
|
---|
1963 | binary data block. For some tags, such as Composite tags where there is no
|
---|
1964 | ID, an empty string is returned. In list context, also returns a language
|
---|
1965 | code for the tag if available and different from the default language (eg.
|
---|
1966 | with alternate language entries for XMP "lang-alt" tags).
|
---|
1967 |
|
---|
1968 | $id = $exifTool->GetTagID($tag);
|
---|
1969 | ($id, $lang) = $exifTool->GetTagID($tag);
|
---|
1970 |
|
---|
1971 | =over 4
|
---|
1972 |
|
---|
1973 | =item Inputs:
|
---|
1974 |
|
---|
1975 | 0) ExifTool object reference
|
---|
1976 |
|
---|
1977 | 1) Tag key
|
---|
1978 |
|
---|
1979 | =item Return Values:
|
---|
1980 |
|
---|
1981 | In scalar context, returns the tag ID or '' if there is no ID for this tag.
|
---|
1982 | In list context, returns the tag ID (or '') and the language code (or
|
---|
1983 | undef).
|
---|
1984 |
|
---|
1985 | =back
|
---|
1986 |
|
---|
1987 | =head2 GetDescription
|
---|
1988 |
|
---|
1989 | Get description for specified tag. This function will always return a
|
---|
1990 | defined value. In the case where the description doesn't exist, one is
|
---|
1991 | generated from the tag name.
|
---|
1992 |
|
---|
1993 | =over 4
|
---|
1994 |
|
---|
1995 | =item Inputs:
|
---|
1996 |
|
---|
1997 | 0) ExifTool object reference
|
---|
1998 |
|
---|
1999 | 1) Tag key
|
---|
2000 |
|
---|
2001 | =item Return Values:
|
---|
2002 |
|
---|
2003 | A description for the specified tag.
|
---|
2004 |
|
---|
2005 | =back
|
---|
2006 |
|
---|
2007 | =head2 GetGroup
|
---|
2008 |
|
---|
2009 | Get group name(s) for a specified tag.
|
---|
2010 |
|
---|
2011 | # return family 0 group name (eg. 'EXIF');
|
---|
2012 | $group = $exifTool->GetGroup($tag, 0);
|
---|
2013 |
|
---|
2014 | # return all groups (eg. qw{EXIF IFD0 Author Main})
|
---|
2015 | @groups = $exifTool->GetGroup($tag);
|
---|
2016 |
|
---|
2017 | # return groups as a string (eg. 'Main:IFD0:Author')
|
---|
2018 | $group = $exifTool->GetGroup($tag, ':3:1:2');
|
---|
2019 |
|
---|
2020 | # return groups as a simplified string (eg. 'IFD0:Author')
|
---|
2021 | $group = $exifTool->GetGroup($tag, '3:1:2');
|
---|
2022 |
|
---|
2023 | =over 4
|
---|
2024 |
|
---|
2025 | =item Inputs:
|
---|
2026 |
|
---|
2027 | 0) ExifTool object reference
|
---|
2028 |
|
---|
2029 | 1) Tag key
|
---|
2030 |
|
---|
2031 | 2) [optional] Group family number, or string of numbers separated by colons
|
---|
2032 |
|
---|
2033 | =item Return Values:
|
---|
2034 |
|
---|
2035 | Group name (or '' if tag has no group). If no group family is specified,
|
---|
2036 | L</GetGroup> returns the name of the group in family 0 when called in scalar
|
---|
2037 | context, or the names of groups for all families in list context. Returns a
|
---|
2038 | string of group names separated by colons if the input group family contains
|
---|
2039 | a colon. The string is simplified to remove a leading 'Main:' and adjacent
|
---|
2040 | identical group names unless the family string begins with a colon.
|
---|
2041 |
|
---|
2042 | =item Notes:
|
---|
2043 |
|
---|
2044 | The group family numbers are currently available:
|
---|
2045 |
|
---|
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)
|
---|
2054 |
|
---|
2055 | Families 0 and 1 are based on the file structure, and are similar except
|
---|
2056 | that family 1 is more specific and sub-divides some groups to give more
|
---|
2057 | detail about the specific location where the information was found. For
|
---|
2058 | example, the EXIF group is split up based on the specific IFD (Image File
|
---|
2059 | Directory), the MakerNotes group is divided into groups for each
|
---|
2060 | manufacturer, and the XMP group is separated based on the XMP namespace
|
---|
2061 | prefix. Note that only common XMP namespaces are listed in the
|
---|
2062 | L<GetAllGroups documentation|/GetAllGroups [static]>, but additional
|
---|
2063 | namespaces may be present in some XMP data. Also note that the 'XMP-xmp...'
|
---|
2064 | group names may appear in the older form 'XMP-xap...' since these names
|
---|
2065 | evolved as the XMP standard was developed. The ICC_Profile group is broken
|
---|
2066 | down to give information about the specific ICC_Profile tag from which
|
---|
2067 | multiple values were extracted. As well, information extracted from the
|
---|
2068 | ICC_Profile header is separated into the ICC-header group.
|
---|
2069 |
|
---|
2070 | Family 2 classifies information based on the logical category to which the
|
---|
2071 | information refers.
|
---|
2072 |
|
---|
2073 | Family 3 gives the document number for tags extracted from embedded
|
---|
2074 | documents, or 'Main' for tags from the main document. (See the
|
---|
2075 | L</ExtractEmbedded> option for extracting tags from embedded documents.)
|
---|
2076 | Nested sub-documents (if they exist) are indicated by numbers separated with
|
---|
2077 | dashes in the group name, to an arbitrary depth. (eg. 'Doc2-3-1' is the 1st
|
---|
2078 | sub-sub-document of the 3rd sub-document of the 2nd embedded document of the
|
---|
2079 | main file.) Document numbers are also used to differentiate samples for
|
---|
2080 | timed metadata in videos.
|
---|
2081 |
|
---|
2082 | Family 4 provides a method for differentiating tags when multiple tags exist
|
---|
2083 | with the same name in the same location. The primary instance of a tag (the
|
---|
2084 | tag extracted when the Duplicates option is disabled and no group is
|
---|
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).
|
---|
2105 |
|
---|
2106 | See L</GetAllGroups [static]> for complete lists of group names.
|
---|
2107 |
|
---|
2108 | =back
|
---|
2109 |
|
---|
2110 | =head2 GetGroups
|
---|
2111 |
|
---|
2112 | Get list of group names that exist in the specified information.
|
---|
2113 |
|
---|
2114 | @groups = $exifTool->GetGroups($info, 2);
|
---|
2115 | @groups = $exifTool->GetGroups('3:1');
|
---|
2116 |
|
---|
2117 | =over 4
|
---|
2118 |
|
---|
2119 | =item Inputs:
|
---|
2120 |
|
---|
2121 | 0) ExifTool object reference
|
---|
2122 |
|
---|
2123 | 1) [optional] Info hash ref (default is all extracted info)
|
---|
2124 |
|
---|
2125 | 2) [optional] Group family number, or string of numbers (default 0)
|
---|
2126 |
|
---|
2127 | =item Return Values:
|
---|
2128 |
|
---|
2129 | List of group names in alphabetical order. If information hash is not
|
---|
2130 | specified, the group names are returned for all extracted information. See
|
---|
2131 | L</GetGroup> for an description of family numbers and family number strings.
|
---|
2132 |
|
---|
2133 | =back
|
---|
2134 |
|
---|
2135 | =head2 BuildCompositeTags
|
---|
2136 |
|
---|
2137 | Builds composite tags from required tags. The composite tags are
|
---|
2138 | convenience tags which are derived from the values of other tags. This
|
---|
2139 | routine is called automatically by L</ImageInfo> and L</ExtractInfo> if the
|
---|
2140 | Composite option is set.
|
---|
2141 |
|
---|
2142 | =over 4
|
---|
2143 |
|
---|
2144 | =item Inputs:
|
---|
2145 |
|
---|
2146 | 0) ExifTool object reference
|
---|
2147 |
|
---|
2148 | =item Return Values:
|
---|
2149 |
|
---|
2150 | (none)
|
---|
2151 |
|
---|
2152 | =item Notes:
|
---|
2153 |
|
---|
2154 | Tag values are calculated in alphabetical order unless a tag Require's or
|
---|
2155 | Desire's another composite tag, in which case the calculation is deferred
|
---|
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.
|
---|
2165 |
|
---|
2166 | =back
|
---|
2167 |
|
---|
2168 | =head2 GetTagName [static]
|
---|
2169 |
|
---|
2170 | Get name of tag from tag key. This is a convenience function that
|
---|
2171 | strips the embedded instance number, if it exists, from the tag key.
|
---|
2172 |
|
---|
2173 | Note: "static" in the heading above indicates that the function does not
|
---|
2174 | require an ExifTool object reference as the first argument. All functions
|
---|
2175 | documented below are also static.
|
---|
2176 |
|
---|
2177 | $tagName = Image::ExifTool::GetTagName($tag);
|
---|
2178 |
|
---|
2179 | =over 4
|
---|
2180 |
|
---|
2181 | =item Inputs:
|
---|
2182 |
|
---|
2183 | 0) Tag key
|
---|
2184 |
|
---|
2185 | =item Return Value:
|
---|
2186 |
|
---|
2187 | Tag name. This is the same as the tag key but has the instance number
|
---|
2188 | removed.
|
---|
2189 |
|
---|
2190 | =back
|
---|
2191 |
|
---|
2192 | =head2 GetShortcuts [static]
|
---|
2193 |
|
---|
2194 | Get a list of shortcut tags.
|
---|
2195 |
|
---|
2196 | =over 4
|
---|
2197 |
|
---|
2198 | =item Inputs:
|
---|
2199 |
|
---|
2200 | (none)
|
---|
2201 |
|
---|
2202 | =item Return Values:
|
---|
2203 |
|
---|
2204 | List of shortcut tags (as defined in Image::ExifTool::Shortcuts).
|
---|
2205 |
|
---|
2206 | =back
|
---|
2207 |
|
---|
2208 | =head2 GetAllTags [static]
|
---|
2209 |
|
---|
2210 | Get list of all available tag names.
|
---|
2211 |
|
---|
2212 | @tagList = Image::ExifTool::GetAllTags($group);
|
---|
2213 |
|
---|
2214 | =over 4
|
---|
2215 |
|
---|
2216 | =item Inputs:
|
---|
2217 |
|
---|
2218 | 0) [optional] Group name, or string of group names separated by colons
|
---|
2219 |
|
---|
2220 | =item Return Values:
|
---|
2221 |
|
---|
2222 | A list of all available tags in alphabetical order, or all tags in a
|
---|
2223 | specified group or intersection of groups. The group name is case
|
---|
2224 | insensitive, and any group in families 0-2 may be used except for EXIF
|
---|
2225 | family 1 groups (ie. the specific IFD).
|
---|
2226 |
|
---|
2227 | =back
|
---|
2228 |
|
---|
2229 | =head2 GetWritableTags [static]
|
---|
2230 |
|
---|
2231 | Get list of all writable tag names.
|
---|
2232 |
|
---|
2233 | @tagList = Image::ExifTool::GetWritableTags($group);
|
---|
2234 |
|
---|
2235 | =over 4
|
---|
2236 |
|
---|
2237 | =item Inputs:
|
---|
2238 |
|
---|
2239 | 0) [optional] Group name, or string of group names separated by colons
|
---|
2240 |
|
---|
2241 | =item Return Values:
|
---|
2242 |
|
---|
2243 | A list of all writable tags in alphabetical order. These are the tags for
|
---|
2244 | which values may be set through L</SetNewValue>. If a group name is given,
|
---|
2245 | returns only writable tags in specified group(s). The group name is case
|
---|
2246 | insensitive, and any group in families 0-2 may be used except for EXIF
|
---|
2247 | family 1 groups (ie. the specific IFD).
|
---|
2248 |
|
---|
2249 | =back
|
---|
2250 |
|
---|
2251 | =head2 GetAllGroups [static]
|
---|
2252 |
|
---|
2253 | Get list of all group names in specified family.
|
---|
2254 |
|
---|
2255 | @groupList = Image::ExifTool::GetAllGroups($family);
|
---|
2256 |
|
---|
2257 | =over 4
|
---|
2258 |
|
---|
2259 | =item Inputs:
|
---|
2260 |
|
---|
2261 | 0) Group family number (0-7)
|
---|
2262 |
|
---|
2263 | =item Return Values:
|
---|
2264 |
|
---|
2265 | A list of all groups in the specified family in alphabetical order.
|
---|
2266 |
|
---|
2267 | =back
|
---|
2268 |
|
---|
2269 | Here is a complete list of groups for each of these families:
|
---|
2270 |
|
---|
2271 | =over 4
|
---|
2272 |
|
---|
2273 | =item Family 0 (Information Type):
|
---|
2274 |
|
---|
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
|
---|
2285 |
|
---|
2286 | =item Family 1 (Specific Location):
|
---|
2287 |
|
---|
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,
|
---|
2294 | HTML-prod, HTML-vw96, HTTP-equiv, ICC-chrm, ICC-clrt, ICC-header, ICC-meas,
|
---|
2295 | ICC-meta, ICC-view, ICC_Profile, ICC_Profile#, ID3, ID3v1, ID3v1_Enh,
|
---|
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,
|
---|
2323 | XMP-rdf, XMP-swf, XMP-tiff, XMP-x, XMP-xmp, XMP-xmpBJ, XMP-xmpDM, XMP-xmpMM,
|
---|
2324 | XMP-xmpNote, XMP-xmpPLUS, XMP-xmpRights, XMP-xmpTPg, ZIP
|
---|
2325 |
|
---|
2326 | =item Family 2 (Category):
|
---|
2327 |
|
---|
2328 | Audio, Author, Camera, Device, Document, ExifTool, Image, Location, Other,
|
---|
2329 | Preview, Printing, Time, Unknown, Video
|
---|
2330 |
|
---|
2331 | =item Family 3 (Document Number):
|
---|
2332 |
|
---|
2333 | Doc#, Main
|
---|
2334 |
|
---|
2335 | =item Family 4 (Instance Number):
|
---|
2336 |
|
---|
2337 | Copy#
|
---|
2338 |
|
---|
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.
|
---|
2359 |
|
---|
2360 | =head2 GetDeleteGroups [static]
|
---|
2361 |
|
---|
2362 | Get list of all deletable group names.
|
---|
2363 |
|
---|
2364 | @delGroups = Image::ExifTool::GetDeleteGroups();
|
---|
2365 |
|
---|
2366 | =over 4
|
---|
2367 |
|
---|
2368 | =item Inputs:
|
---|
2369 |
|
---|
2370 | None.
|
---|
2371 |
|
---|
2372 | =item Return Values:
|
---|
2373 |
|
---|
2374 | A list of deletable group names in alphabetical order. The current list of
|
---|
2375 | deletable group names is:
|
---|
2376 |
|
---|
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.
|
---|
2399 |
|
---|
2400 | =back
|
---|
2401 |
|
---|
2402 | =head2 GetFileType [static]
|
---|
2403 |
|
---|
2404 | Get type of file given file name.
|
---|
2405 |
|
---|
2406 | my $type = Image::ExifTool::GetFileType($filename);
|
---|
2407 | my $desc = Image::ExifTool::GetFileType($filename, 1);
|
---|
2408 |
|
---|
2409 | =over 4
|
---|
2410 |
|
---|
2411 | =item Inputs:
|
---|
2412 |
|
---|
2413 | 0) [optional] File name (or just an extension)
|
---|
2414 |
|
---|
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.
|
---|
2419 |
|
---|
2420 | =item Return Value:
|
---|
2421 |
|
---|
2422 | A string, based on the file extension, which indicates the basic format of
|
---|
2423 | the file. Note that some files may be based on other formats (like many RAW
|
---|
2424 | 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
|
---|
2430 | description flag is set.
|
---|
2431 |
|
---|
2432 | =back
|
---|
2433 |
|
---|
2434 | =head2 CanWrite [static]
|
---|
2435 |
|
---|
2436 | Can the specified file be written?
|
---|
2437 |
|
---|
2438 | my $writable = Image::ExifTool::CanWrite($filename);
|
---|
2439 |
|
---|
2440 | =over 4
|
---|
2441 |
|
---|
2442 | =item Inputs:
|
---|
2443 |
|
---|
2444 | 0) File name or extension
|
---|
2445 |
|
---|
2446 | =item Return Value:
|
---|
2447 |
|
---|
2448 | True if ExifTool supports writing files of this type (based on the file
|
---|
2449 | extension).
|
---|
2450 |
|
---|
2451 | =back
|
---|
2452 |
|
---|
2453 | =head2 CanCreate [static]
|
---|
2454 |
|
---|
2455 | Can the specified file be created?
|
---|
2456 |
|
---|
2457 | my $creatable = Image::ExifTool::CanCreate($filename);
|
---|
2458 |
|
---|
2459 | =over 4
|
---|
2460 |
|
---|
2461 | =item Inputs:
|
---|
2462 |
|
---|
2463 | 0) File name or extension
|
---|
2464 |
|
---|
2465 | =item Return Value:
|
---|
2466 |
|
---|
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.
|
---|
2505 |
|
---|
2506 | =back
|
---|
2507 |
|
---|
2508 | =head1 CHARACTER ENCODINGS
|
---|
2509 |
|
---|
2510 | Certain meta information formats allow coded character sets other than plain
|
---|
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.
|
---|
2555 |
|
---|
2556 | More specific details are given below about how character coding is handled
|
---|
2557 | for EXIF, IPTC, XMP, PNG, ID3, PDF, Photoshop, QuickTime, AIFF, MIE and
|
---|
2558 | Vorbis information:
|
---|
2559 |
|
---|
2560 | =head2 EXIF
|
---|
2561 |
|
---|
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,
|
---|
2580 | text is stored as ASCII unless the string contains special characters, in
|
---|
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.
|
---|
2590 |
|
---|
2591 | =head2 IPTC
|
---|
2592 |
|
---|
2593 | The value of the IPTC:CodedCharacterSet tag determines how the internal IPTC
|
---|
2594 | string values are interpreted. If CodedCharacterSet exists and has a value
|
---|
2595 | of 'UTF8' (or 'ESC % G') then string values are assumed to be stored as
|
---|
2596 | UTF-8, otherwise Windows Latin1 (cp1252, 'Latin') coding is assumed by
|
---|
2597 | default, but this can be changed with the L</CharsetIPTC> option. When
|
---|
2598 | reading, these strings are converted to the character set specified by the
|
---|
2599 | L</Charset> option. When writing, the inverse conversions are performed.
|
---|
2600 | No conversion is done if the internal (IPTC) and external (ExifTool)
|
---|
2601 | character sets are the same. Note that ISO 2022 character set shifting is
|
---|
2602 | not supported. Instead, a warning is issued and the string is not converted
|
---|
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.)
|
---|
2634 |
|
---|
2635 | =head2 XMP
|
---|
2636 |
|
---|
2637 | ExifTool reads XMP encoded as UTF-8, UTF-16 or UTF-32, and converts them all
|
---|
2638 | to UTF-8 internally. Also, all XML character entity references and numeric
|
---|
2639 | character references are converted. When writing, ExifTool always encodes
|
---|
2640 | XMP as UTF-8, converting the following 5 characters to XML character
|
---|
2641 | references: E<amp> E<lt> E<gt> E<39> E<quot>. By default no further
|
---|
2642 | conversion is performed, however if the L</Charset> option is other than
|
---|
2643 | 'UTF8' then text is converted to/from the specified character set when
|
---|
2644 | reading/writing.
|
---|
2645 |
|
---|
2646 | =head2 PNG
|
---|
2647 |
|
---|
2648 | L<PNG TextualData tags|Image::ExifTool::TagNames/"PNG TextualData Tags"> are
|
---|
2649 | stored as tEXt, zTXt and iTXt chunks in PNG images. The tEXt and zTXt
|
---|
2650 | chunks use ISO 8859-1 encoding, while iTXt uses UTF-8. When reading,
|
---|
2651 | ExifTool converts all PNG textual data to the character set specified by the
|
---|
2652 | L</Charset> option. When writing, ExifTool generates a tEXt chunk (or zTXt
|
---|
2653 | with the L</Compress> option) if the text doesn't contain special characters
|
---|
2654 | or if Latin encoding is specified; otherwise an iTXt chunk is used and the
|
---|
2655 | text is converted from the specified character set and stored as UTF-8.
|
---|
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 |
|
---|
2662 | =head2 ID3
|
---|
2663 |
|
---|
2664 | The ID3v1 specification officially supports only ISO 8859-1 encoding (a
|
---|
2665 | subset of Windows Latin1), although some applications may incorrectly use
|
---|
2666 | other character sets. By default ExifTool converts ID3v1 text from Latin to
|
---|
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.
|
---|
2672 |
|
---|
2673 | =head2 PDF
|
---|
2674 |
|
---|
2675 | PDF text strings are stored in either PDFDocEncoding (similar to Windows
|
---|
2676 | Latin1) or Unicode (UCS-2). When reading, ExifTool converts to the
|
---|
2677 | character set specified by the L</Charset> option. When writing, ExifTool
|
---|
2678 | encodes input text from the specified character set as Unicode only if the
|
---|
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.
|
---|
2706 |
|
---|
2707 | =head2 MIE
|
---|
2708 |
|
---|
2709 | MIE strings are stored as either UTF-8 or ISO 8859-1. When reading, UTF-8
|
---|
2710 | strings are converted according to the L</Charset> option, and ISO 8859-1
|
---|
2711 | strings are never converted. When writing, input strings are converted from
|
---|
2712 | the specified character set to UTF-8. The resulting strings are stored as
|
---|
2713 | UTF-8 if they contain multi-byte UTF-8 character sequences, otherwise they
|
---|
2714 | are stored as ISO 8859-1.
|
---|
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 |
|
---|
2721 | =head1 AUTHOR
|
---|
2722 |
|
---|
2723 | Copyright 2003-2021, Phil Harvey
|
---|
2724 |
|
---|
2725 | This library is free software; you can redistribute it and/or modify it
|
---|
2726 | under the same terms as Perl itself.
|
---|
2727 |
|
---|
2728 | =head1 ACKNOWLEDGEMENTS
|
---|
2729 |
|
---|
2730 | Many people have helped in the development of ExifTool through their bug
|
---|
2731 | reports, comments and suggestions, and/or additions to the code. See the
|
---|
2732 | ACKNOWLEDGEMENTS in the individual Image::ExifTool modules and in
|
---|
2733 | html/index.html of the Image::ExifTool distribution package for a list of
|
---|
2734 | people who have contributed to this project.
|
---|
2735 |
|
---|
2736 | =head1 SEE ALSO
|
---|
2737 |
|
---|
2738 | L<exiftool(1)|exiftool>,
|
---|
2739 | L<Image::ExifTool::TagNames(3pm)|Image::ExifTool::TagNames>,
|
---|
2740 | L<Image::ExifTool::Shortcuts(3pm)|Image::ExifTool::Shortcuts>,
|
---|
2741 | L<Image::ExifTool::Shift(3pm)|Image::ExifTool::Shift.pl>,
|
---|
2742 | L<Image::Info(3pm)|Image::Info>,
|
---|
2743 | L<Image::MetaData::JPEG(3pm)|Image::MetaData::JPEG>
|
---|
2744 |
|
---|
2745 | =cut
|
---|
2746 |
|
---|
2747 | # end
|
---|