ExifTool.pod 92 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382138313841385138613871388138913901391139213931394139513961397139813991400140114021403140414051406140714081409141014111412141314141415141614171418141914201421142214231424142514261427142814291430143114321433143414351436143714381439144014411442144314441445144614471448144914501451145214531454145514561457145814591460146114621463146414651466146714681469147014711472147314741475147614771478147914801481148214831484148514861487148814891490149114921493149414951496149714981499150015011502150315041505150615071508150915101511151215131514151515161517151815191520152115221523152415251526152715281529153015311532153315341535153615371538153915401541154215431544154515461547154815491550155115521553155415551556155715581559156015611562156315641565156615671568156915701571157215731574157515761577157815791580158115821583158415851586158715881589159015911592159315941595159615971598159916001601160216031604160516061607160816091610161116121613161416151616161716181619162016211622162316241625162616271628162916301631163216331634163516361637163816391640164116421643164416451646164716481649165016511652165316541655165616571658165916601661166216631664166516661667166816691670167116721673167416751676167716781679168016811682168316841685168616871688168916901691169216931694169516961697169816991700170117021703170417051706170717081709171017111712171317141715171617171718171917201721172217231724172517261727172817291730173117321733173417351736173717381739174017411742174317441745174617471748174917501751175217531754175517561757175817591760176117621763176417651766176717681769177017711772177317741775177617771778177917801781178217831784178517861787178817891790179117921793179417951796179717981799180018011802180318041805180618071808180918101811181218131814181518161817181818191820182118221823182418251826182718281829183018311832183318341835183618371838183918401841184218431844184518461847184818491850185118521853185418551856185718581859186018611862186318641865186618671868186918701871187218731874187518761877187818791880188118821883188418851886188718881889189018911892189318941895189618971898189919001901190219031904190519061907190819091910191119121913191419151916191719181919192019211922192319241925192619271928192919301931193219331934193519361937193819391940194119421943194419451946194719481949195019511952195319541955195619571958195919601961196219631964196519661967196819691970197119721973197419751976197719781979198019811982198319841985198619871988198919901991199219931994199519961997199819992000200120022003200420052006200720082009201020112012201320142015201620172018201920202021202220232024202520262027202820292030203120322033203420352036203720382039204020412042204320442045204620472048204920502051205220532054205520562057205820592060206120622063206420652066206720682069207020712072207320742075207620772078207920802081208220832084208520862087208820892090209120922093209420952096209720982099210021012102210321042105210621072108210921102111211221132114211521162117211821192120212121222123212421252126212721282129213021312132213321342135213621372138213921402141214221432144214521462147214821492150215121522153215421552156215721582159216021612162216321642165216621672168216921702171217221732174217521762177217821792180218121822183218421852186218721882189219021912192219321942195219621972198219922002201220222032204220522062207220822092210221122122213221422152216221722182219222022212222222322242225222622272228222922302231223222332234223522362237223822392240224122422243224422452246224722482249225022512252225322542255225622572258225922602261226222632264226522662267226822692270227122722273227422752276227722782279228022812282228322842285228622872288228922902291229222932294229522962297229822992300230123022303230423052306230723082309231023112312231323142315231623172318231923202321232223232324232523262327232823292330233123322333233423352336233723382339234023412342234323442345234623472348234923502351235223532354235523562357235823592360236123622363236423652366236723682369237023712372237323742375237623772378237923802381238223832384238523862387238823892390239123922393239423952396239723982399240024012402240324042405240624072408240924102411241224132414241524162417241824192420242124222423242424252426242724282429243024312432243324342435243624372438243924402441244224432444244524462447244824492450245124522453245424552456245724582459246024612462246324642465246624672468246924702471247224732474247524762477247824792480248124822483248424852486248724882489249024912492249324942495249624972498249925002501250225032504250525062507250825092510251125122513251425152516251725182519252025212522252325242525252625272528
  1. #------------------------------------------------------------------------------
  2. # File: ExifTool.pod - Documentation for File::ExifTool
  3. #
  4. # Description: Read and write meta information
  5. #
  6. # URL: http://owl.phy.queensu.ca/~phil/exiftool/
  7. #
  8. # Legal: Copyright (c) 2003-2016, Phil Harvey (phil at owl.phy.queensu.ca)
  9. # This library is free software; you can redistribute it and/or
  10. # modify it under the same terms as Perl itself.
  11. #------------------------------------------------------------------------------
  12. =head1 NAME
  13. Image::ExifTool - Read and write meta information
  14. =head1 SYNOPSIS
  15. use Image::ExifTool qw(:Public);
  16. # ---- Simple procedural usage ----
  17. # Get hash of meta information tag names/values from an image
  18. $info = ImageInfo('a.jpg');
  19. # ---- Object-oriented usage ----
  20. # Create a new Image::ExifTool object
  21. $exifTool = new Image::ExifTool;
  22. # Extract meta information from an image
  23. $exifTool->ExtractInfo($file, \%options);
  24. # Get list of tags in the order they were found in the file
  25. @tagList = $exifTool->GetFoundTags('File');
  26. # Get the value of a specified tag
  27. $value = $exifTool->GetValue($tag, $type);
  28. # Get a tag description
  29. $description = $exifTool->GetDescription($tag);
  30. # Get the group name associated with this tag
  31. $group = $exifTool->GetGroup($tag, $family);
  32. # Set a new value for a tag
  33. $exifTool->SetNewValue($tag, $newValue);
  34. # Write new meta information to a file
  35. $success = $exifTool->WriteInfo($srcfile, $dstfile);
  36. # ...plus a host of other useful methods...
  37. =head1 DESCRIPTION
  38. Reads and writes meta information in a wide variety of files, including the
  39. maker notes of many digital cameras by various manufacturers such as Canon,
  40. Casio, FLIR, FujiFilm, GE, HP, JVC/Victor, Kodak, Leaf,
  41. Minolta/Konica-Minolta, Nikon, Nintendo, Olympus/Epson, Panasonic/Leica,
  42. Pentax/Asahi, Phase One, Reconyx, Ricoh, Samsung, Sanyo, Sigma/Foveon and
  43. Sony.
  44. Below is a list of file types and meta information formats currently
  45. supported by ExifTool (r = read, w = write, c = create):
  46. File Types
  47. ------------+-------------+-------------+-------------+------------
  48. 3FR r | DVB r/w | KEY r | ORF r/w | RWL r/w
  49. 3G2 r/w | DYLIB r | LA r | OTF r | RWZ r
  50. 3GP r/w | EIP r | LFP r | PAC r | RM r
  51. AA r | EPS r/w | LNK r | PAGES r | SEQ r
  52. AAX r/w | EPUB r | M2TS r | PBM r/w | SO r
  53. ACR r | ERF r/w | M4A/V r/w | PCD r | SR2 r/w
  54. AFM r | EXE r | MEF r/w | PDB r | SRF r
  55. AI r/w | EXIF r/w/c | MIE r/w/c | PDF r/w | SRW r/w
  56. AIFF r | EXR r | MIFF r | PEF r/w | SVG r
  57. APE r | EXV r/w/c | MKA r | PFA r | SWF r
  58. ARW r/w | F4A/V r/w | MKS r | PFB r | THM r/w
  59. ASF r | FFF r/w | MKV r | PFM r | TIFF r/w
  60. AVI r | FLA r | MNG r/w | PGF r | TORRENT r
  61. AZW r | FLAC r | MOBI r | PGM r/w | TTC r
  62. BMP r | FLV r | MODD r | PLIST r | TTF r
  63. BTF r | FPF r | MOI r | PICT r | VCF r
  64. CHM r | FPX r | MOS r/w | PMP r | VRD r/w/c
  65. COS r | GIF r/w | MOV r/w | PNG r/w | VSD r
  66. CR2 r/w | GZ r | MP3 r | PPM r/w | WAV r
  67. CRW r/w | HDP r/w | MP4 r/w | PPT r | WDP r/w
  68. CS1 r/w | HDR r | MPC r | PPTX r | WEBP r
  69. DCM r | HTML r | MPG r | PS r/w | WEBM r
  70. DCP r/w | ICC r/w/c | MPO r/w | PSB r/w | WMA r
  71. DCR r | ICS r | MQV r/w | PSD r/w | WMV r
  72. DFONT r | IDML r | MRW r/w | PSP r | WV r
  73. DIVX r | IIQ r/w | MXF r | QTIF r/w | X3F r/w
  74. DJVU r | IND r/w | NEF r/w | RA r | XCF r
  75. DLL r | INX r | NRW r/w | RAF r/w | XLS r
  76. DNG r/w | ITC r | NUMBERS r | RAM r | XLSX r
  77. DOC r | J2C r | ODP r | RAR r | XMP r/w/c
  78. DOCX r | JNG r/w | ODS r | RAW r/w | ZIP r
  79. DPX r | JP2 r/w | ODT r | RIFF r |
  80. DR4 r/w/c | JPEG r/w | OFR r | RSRC r |
  81. DSS r | K25 r | OGG r | RTF r |
  82. DV r | KDC r | OGV r | RW2 r/w |
  83. Meta Information
  84. ----------------------+----------------------+---------------------
  85. EXIF r/w/c | CIFF r/w | Ricoh RMETA r
  86. GPS r/w/c | AFCP r/w | Picture Info r
  87. IPTC r/w/c | Kodak Meta r/w | Adobe APP14 r
  88. XMP r/w/c | FotoStation r/w | MPF r
  89. MakerNotes r/w/c | PhotoMechanic r/w | Stim r
  90. Photoshop IRB r/w/c | JPEG 2000 r | DPX r
  91. ICC Profile r/w/c | DICOM r | APE r
  92. MIE r/w/c | Flash r | Vorbis r
  93. JFIF r/w/c | FlashPix r | SPIFF r
  94. Ducky APP12 r/w/c | QuickTime r | DjVu r
  95. PDF r/w/c | Matroska r | M2TS r
  96. PNG r/w/c | MXF r | PE/COFF r
  97. Canon VRD r/w/c | PrintIM r | AVCHD r
  98. Nikon Capture r/w/c | FLAC r | ZIP r
  99. GeoTIFF r/w/c | ID3 r | (and more)
  100. =head1 CONFIGURATION
  101. User-defined tags can be added via the ExifTool configuration file, or by
  102. defining the %Image::ExifTool::UserDefined hash before calling any ExifTool
  103. methods. See "ExifTool_config" in the ExifTool distribution for more
  104. details.
  105. By default ExifTool looks for a configuration file named ".ExifTool_config"
  106. first in your home directory, then in the directory of the application
  107. script, but a different directory may be specified by setting the
  108. EXIFTOOL_HOME environment variable, or a different file may be specified by
  109. setting the ExifTool C<configFile> variable before using Image::ExifTool.
  110. For example:
  111. BEGIN { $Image::ExifTool::configFile = '/Users/phil/myconfig.cfg' }
  112. use Image::ExifTool;
  113. The configuration feature may also be disabled by setting C<configFile> to
  114. an empty string:
  115. BEGIN { $Image::ExifTool::configFile = '' }
  116. use Image::ExifTool;
  117. =head1 EXPORTS
  118. Exports nothing by default, but L</ImageInfo> and all static methods may be
  119. exported with the C<:Public> export list.
  120. =head1 METHODS
  121. All ExifTool features are accessed through the methods of the public
  122. interface listed below. Other Image::ExifTool methods and modules should
  123. not be accessed directly because their interface may change with future
  124. versions.
  125. None of these methods should ever die or issue warnings to STDERR if called
  126. with the proper arguments (with the exception of L</SetNewValue> which may
  127. send an error message to STDERR, but only when called in scalar context).
  128. Error and warning messages that occur during processing are stored in the
  129. values of the Error and Warning tags, and are accessible via the
  130. L</GetValue> method to retrieve a single Error or Warning message, or
  131. L</GetInfo> to retrieve any number of them.
  132. The ExifTool methods are not thread safe.
  133. =head2 new
  134. Creates a new ExifTool object.
  135. $exifTool = new Image::ExifTool;
  136. Note that ExifTool uses AUTOLOAD to load non-member methods, so any class
  137. using Image::ExifTool as a base class must define an AUTOLOAD which calls
  138. Image::ExifTool::DoAutoLoad(). eg)
  139. sub AUTOLOAD
  140. {
  141. Image::ExifTool::DoAutoLoad($AUTOLOAD, @_);
  142. }
  143. =head2 ImageInfo
  144. Read image file and return meta information. This is the one step function
  145. for retrieving meta information from an image. Internally, L</ImageInfo>
  146. calls L</ExtractInfo> to extract the information, L</GetInfo> to generate
  147. the information hash, and L</GetTagList> for the returned tag list.
  148. # return meta information for 2 tags only (procedural)
  149. $info = ImageInfo($filename, $tag1, $tag2);
  150. # return information about an open image file (object-oriented)
  151. $info = $exifTool->ImageInfo(\*FILE);
  152. # return information from image data in memory for specified tags
  153. %options = (PrintConv => 0);
  154. @tagList = qw(filename imagesize xmp:creator exif:* -ifd1:*);
  155. $info = ImageInfo(\$imageData, \@tagList, \%options);
  156. # extract information from an embedded thumbnail image
  157. $info = ImageInfo('image.jpg', 'thumbnailimage');
  158. $thumbInfo = ImageInfo($$info{ThumbnailImage});
  159. =over 4
  160. =item Inputs:
  161. L</ImageInfo> is very flexible about the input arguments, and interprets
  162. them based on their type. It may be called with one or more arguments.
  163. The one required argument is either a SCALAR (the image file name), a file
  164. reference (a reference to the image file) or a SCALAR reference (a
  165. reference to the image in memory). Other arguments are optional. The
  166. order of the arguments is not significant, except that the first SCALAR is
  167. taken to be the file name unless a file reference or scalar reference comes
  168. earlier in the argument list.
  169. Below is an explanation of how the L</ImageInfo> function arguments are
  170. interpreted:
  171. =over 4
  172. =item ExifTool ref
  173. L</ImageInfo> may be called with an ExifTool object if desired. Advantages
  174. of using the object-oriented form are that options may be set before calling
  175. L</ImageInfo>, and the object may be used afterward to access member
  176. functions. Must be the first argument if used.
  177. =item SCALAR
  178. The first scalar argument is taken to be the file name unless an earlier
  179. argument specified the image data via a file reference (file ref) or data
  180. reference (SCALAR ref). The remaining scalar arguments are names of tags
  181. for requested information. All tags are returned if no tags are specified.
  182. Tag names are case-insensitive and may be prefixed by optional group names
  183. separated by colons. A group name may begin with a family number (eg.
  184. '1IPTC:Keywords'), to restrict matches to a specific family. In the tag
  185. name, a '?' matches any single character and a '*' matches zero or more
  186. characters. Thus 'GROUP:*' represents all tags in a specific group.
  187. Wildcards may not be used in group names, with the exception that a group
  188. name of '*' may be used to extract all available instances of a tag
  189. regardless of the L</Duplicates> setting (eg. '*:WhiteBalance'). Multiple
  190. groups may be specified (eg. 'EXIF:Time:*' extracts all EXIF Time tags). And
  191. finally, a leading '-' indicates a tag to be excluded (eg. '-IFD1:*'), or a
  192. trailing '#' causes the ValueConv value to be returned for this tag.
  193. Note that keys in the returned information hash and elements of the returned
  194. tag list are not necessarily the same as these tag names because group names
  195. are removed, the case may be changed, and an instance number may be added.
  196. For this reason it is best to use either the keys of the returned hash or
  197. the elements of the returned tag list when accessing the tag values.
  198. See L<Image::ExifTool::TagNames|Image::ExifTool::TagNames> for a complete
  199. list of ExifTool tag names.
  200. =item File ref
  201. A reference to an open image file. If you use this method (or a SCALAR
  202. reference) to access information in an image, the FileName and Directory
  203. tags will not be returned. (Also, a number of the File System tags will not
  204. be returned unless it is a plain file.) Image processing begins at the
  205. current file position, and on return the file position is unspecified. May
  206. be either a standard filehandle, or a reference to a
  207. L<File::RandomAccess|File::RandomAccess> object. Note that the file remains
  208. open and must be closed by the caller after L</ImageInfo> returns.
  209. [Advanced: To allow a non-rewindable stream (eg. a network socket) to be
  210. re-read after processing with ExifTool, first wrap the file reference in a
  211. L<File::RandomAccess|File::RandomAccess> object, then pass this object to
  212. L</ImageInfo>. The L<File::RandomAccess|File::RandomAccess> object will
  213. buffer the file if necessary, and may be used to re-read the file after
  214. L</ImageInfo> returns.]
  215. =item SCALAR ref
  216. A reference to image data in memory.
  217. =item ARRAY ref
  218. Reference to a list of tag names. On entry, any elements in the list are
  219. added to the list of requested tags. Tags with names beginning with '-' are
  220. excluded. On return, this list is updated to contain an ordered list of tag
  221. keys for the returned information.
  222. There will be 1:1 correspondence between the requested tags and the returned
  223. tag keys only if the L</Duplicates> option is 0 and L</Sort> is 'Input'.
  224. (With L</Duplicates> enabled, there may be more entries in the returned list
  225. of tag keys, and with other L</Sort> settings the entries may not be in the
  226. same order as requested.) If a requested tag doesn't exist, a tag key is
  227. still generated, but the tag value is undefined.
  228. =item HASH ref
  229. Reference to a hash containing the options settings. See L</Options>
  230. documentation below for a list of available options. Options specified
  231. as arguments to L</ImageInfo> take precedence over L</Options> settings.
  232. =back
  233. =item Return Values:
  234. L</ImageInfo> returns a reference to a hash of tag key/value pairs. The tag
  235. keys are identifiers, which are similar to the tag names but may have an
  236. appended instance number if multiple tags with the same name were extracted
  237. from the image. Many of the ExifTool functions require a tag key as an
  238. argument. Use L</GetTagName [static]> to get the tag name for a given tag
  239. key. Note that the case of the tag names may not be the same as requested.
  240. Here is a simple example to print out the information returned by
  241. L</ImageInfo>:
  242. foreach (sort keys %$info) {
  243. print "$_ => $$info{$_}\n";
  244. }
  245. Values of the returned hash are usually simple scalars, but a scalar
  246. reference is used to indicate binary data and an array reference may be used
  247. to indicate a list. Also, a hash reference may be returned if the L</Struct>
  248. option is used. Lists of values are joined by commas into a single
  249. string only if the PrintConv option is enabled and the List option is
  250. disabled (which are the defaults). Note that binary values are not
  251. necessarily extracted unless specifically requested, or the Binary option is
  252. enabled and the tag is not specifically excluded. If not extracted the
  253. value is a reference to a string of the form "Binary data ##### bytes".
  254. The code below gives an example of how to handle these return values, as
  255. well as illustrating the use of other ExifTool functions:
  256. use Image::ExifTool;
  257. my $exifTool = new Image::ExifTool;
  258. $exifTool->Options(Unknown => 1);
  259. my $info = $exifTool->ImageInfo('a.jpg');
  260. my $group = '';
  261. my $tag;
  262. foreach $tag ($exifTool->GetFoundTags('Group0')) {
  263. if ($group ne $exifTool->GetGroup($tag)) {
  264. $group = $exifTool->GetGroup($tag);
  265. print "---- $group ----\n";
  266. }
  267. my $val = $info->{$tag};
  268. if (ref $val eq 'SCALAR') {
  269. if ($$val =~ /^Binary data/) {
  270. $val = "($$val)";
  271. } else {
  272. my $len = length($$val);
  273. $val = "(Binary data $len bytes)";
  274. }
  275. }
  276. printf("%-32s : %s\n", $exifTool->GetDescription($tag), $val);
  277. }
  278. =item Notes:
  279. ExifTool returns all values as byte strings of encoded characters. Perl
  280. wide characters are not used. See L</CHARACTER ENCODINGS> for details about
  281. the encodings. By default, most returned values are encoded in UTF-8. For
  282. these, Encode::decode_utf8() may be used to convert to a sequence of logical
  283. Perl characters.
  284. As well as tags representing information extracted from the image, the
  285. following L<Extra tags|Image::ExifTool::TagNames/Extra Tags> generated by
  286. ExifTool may be returned:
  287. ExifToolVersion - The ExifTool version number.
  288. Error - An error message if the image could not be processed.
  289. Warning - A warning message if problems were encountered while
  290. processing the image.
  291. =back
  292. =head2 Options
  293. Get/set ExifTool options. This function can be called to set the default
  294. options for an ExifTool object. Options set this way are in effect for
  295. all function calls but may be overridden by options passed as arguments
  296. to some functions. Option names are not case sensitive.
  297. The default option values may be changed by defining a
  298. %Image::ExifTool::UserDefined::Options hash. See the ExifTool_config file
  299. in the full ExifTool distribution for examples.
  300. # exclude the 'OwnerName' tag from returned information
  301. $exifTool->Options(Exclude => 'OwnerName');
  302. # only get information in EXIF or MakerNotes groups
  303. $exifTool->Options(Group0 => ['EXIF', 'MakerNotes']);
  304. # ignore information from IFD1
  305. $exifTool->Options(Group1 => '-IFD1');
  306. # sort by groups in family 2, and extract unknown tags
  307. $exifTool->Options(Sort => 'Group2', Unknown => 1);
  308. # reset DateFormat option
  309. $exifTool->Options(DateFormat => undef);
  310. # do not extract duplicate tag names
  311. $oldSetting = $exifTool->Options(Duplicates => 0);
  312. # get current Verbose setting
  313. $isVerbose = $exifTool->Options('Verbose');
  314. # set a user parameter
  315. $exifTool->Options(UserParam => 'MyParam=some value');
  316. =over 4
  317. =item Inputs:
  318. 0) ExifTool object reference
  319. 1) Option parameter name (case-insensitive)
  320. 2) [optional] Option parameter value (may be undef to clear option)
  321. 3-N) [optional] Additional parameter/value pairs
  322. =item Option Parameters:
  323. =over 4
  324. =item Binary
  325. Flag to extract the value data for all binary tags. Tag values representing
  326. large binary data blocks (eg. ThumbnailImage) are not necessarily extracted
  327. unless this option is set or the tag is specifically requested by name.
  328. Default is undef.
  329. =item ByteOrder
  330. The byte order for newly created EXIF segments when writing. Note that if
  331. EXIF information already exists, the existing order is maintained. Valid
  332. values are 'MM', 'II' and undef. If ByteOrder is not defined (the default),
  333. then the maker note byte order is used (if they are being copied), otherwise
  334. big-endian ('MM') order is assumed. This can also be set via the
  335. L<ExifByteOrder tag|Image::ExifTool::TagNames/Extra Tags>, but the ByteOrder
  336. option takes precedence if both are set.
  337. =item Charset
  338. Character set for encoding character tag values passed to/from ExifTool with
  339. code points above U+007F. Default is 'UTF8'. Valid values are listed
  340. below, case is not significant:
  341. Value Alias(es) Description
  342. ----------- --------------- ----------------------------------
  343. UTF8 cp65001, UTF-8 UTF-8 characters
  344. Latin cp1252, Latin1 Windows Latin1 (West European)
  345. Latin2 cp1250 Windows Latin2 (Central European)
  346. Cyrillic cp1251, Russian Windows Cyrillic
  347. Greek cp1253 Windows Greek
  348. Turkish cp1254 Windows Turkish
  349. Hebrew cp1255 Windows Hebrew
  350. Arabic cp1256 Windows Arabic
  351. Baltic cp1257 Windows Baltic
  352. Vietnam cp1258 Windows Vietnamese
  353. Thai cp874 Windows Thai
  354. MacRoman cp10000, Roman Macintosh Roman
  355. MacLatin2 cp10029 Macintosh Latin2 (Central Europe)
  356. MacCyrillic cp10007 Macintosh Cyrillic
  357. MacGreek cp10006 Macintosh Greek
  358. MacTurkish cp10081 Macintosh Turkish
  359. MacRomanian cp10010 Macintosh Romanian
  360. MacIceland cp10079 Macintosh Icelandic
  361. MacCroatian cp10082 Macintosh Croatian
  362. Note that this option affects some types of information when reading/writing
  363. the file and other types when getting/setting tag values, so it must be
  364. defined for both types of access. See the L</CHARACTER ENCODINGS> section
  365. for more information about the handling of special characters.
  366. =item CharsetEXIF
  367. Internal encoding to use for stored EXIF "ASCII" string values. May also be
  368. set to undef to pass through EXIF "ASCII" values without recoding. Set to
  369. "UTF8" to conform with the MWG recommendation. Default is undef.
  370. =item CharsetFileName
  371. External character set used for file names passed to ExifTool functions.
  372. When set in Windows, this triggers use of Windows wide-character i/o library
  373. routines (requires Win32API::File). Default is undef.
  374. =item CharsetID3
  375. Internal encoding to assume for ID3v1 strings. By the specification ID3v1
  376. strings should be encoded in ISO 8859-1 (essentially Latin), but some
  377. applications may use local encoding instead. Default is 'Latin'.
  378. =item CharsetIPTC
  379. Fallback internal IPTC character set to assume if IPTC information contains
  380. no CodedCharacterSet tag. Possible values are the same as the L</Charset>
  381. option. Default is 'Latin'.
  382. Note that this option affects some types of information when reading/writing
  383. the file and other types when getting/setting tag values, so it must be
  384. defined for both types of access.
  385. =item CharsetPhotoshop
  386. Internal encoding to assume for Photoshop IRB resource names. Default is
  387. 'Latin'.
  388. =item CharsetQuickTime
  389. Internal encoding to assume for QuickTime strings stored with an unspecified
  390. encoding. Default is 'MacRoman'.
  391. =item Compact
  392. Flag to write compact output. Default is undef. The XMP specification
  393. suggests that the data be padded with blanks to allow in-place editing.
  394. With this flag set the 2kB of padding is not written. Note that this only
  395. effects embedded XMP since padding is never written for stand-alone XMP
  396. files.
  397. =item Composite
  398. Flag to generate Composite tags when extracting information. Default is 1.
  399. =item Compress
  400. Flag to write new values in compressed format if possible. Has no effect
  401. unless Compress::Zlib is installed. Default is undef.
  402. =item CoordFormat
  403. Format for printing GPS coordinates. This is a printf format string with
  404. specifiers for degrees, minutes and seconds in that order, however minutes
  405. and seconds may be omitted. If the hemisphere is known, a reference
  406. direction (N, S, E or W) is appended to each printed coordinate, but adding
  407. a C<+> to the first format specifier (eg. C<%+.6f>) prints a signed
  408. coordinate instead. For example, the following table gives the output for
  409. the same coordinate using various formats:
  410. CoordFormat Example Output
  411. ------------------- ------------------
  412. q{%d deg %d' %.2f"} 54 deg 59' 22.80" (default for reading)
  413. q{%d %d %.8f} 54 59 22.80000000 (default for copying)
  414. q{%d deg %.4f min} 54 deg 59.3800 min
  415. q{%.6f degrees} 54.989667 degrees
  416. Note: To avoid loss of precision, the default coordinate format is
  417. different when copying tags with L</SetNewValuesFromFile>.
  418. =item DateFormat
  419. Format for printing date/time values. See C<strftime> in the L<POSIX>
  420. package for details about the format string. The default is similar to a
  421. format of "%Y:%m:%d %H:%M:%S". If date can not be converted, value is left
  422. unchanged unless the StrictDate option is set. Timezones are ignored.
  423. =item Duplicates
  424. Flag to return values from tags with duplicate names when extracting
  425. information. Default is 1.
  426. =item Escape
  427. Escape special characters in extracted values for HTML or XML. Also
  428. unescapes HTML or XML character entities in input values passed to
  429. L</SetNewValue>. Valid settings are 'HTML', 'XML' or undef. Default is
  430. undef.
  431. =item Exclude
  432. Exclude specified tags from tags extracted from an image. The option value
  433. is either a tag name or reference to a list of tag names to exclude. The
  434. case of tag names is not significant. This option is ignored for
  435. specifically requested tags. Tags may also be excluded by preceding their
  436. name with a '-' in the arguments to L</ImageInfo>.
  437. =item ExtendedXMP
  438. This setting affects the reading and editing of extended XMP in JPEG images.
  439. According to the XMP specification, extended XMP is only valid if it has the
  440. GUID specified by the HasExtendedXMP tag. ExifTool 9.95 and earlier would
  441. read extended XMP regardless of GUID, but with the addition of this option
  442. in version 9.96 the default behaviour was changed to conform with the XMP
  443. specification (to read only extended XMP with the proper GUID). This option
  444. should be set to 2 to emulate pre-9.96 behaviour and read all extended XMP.
  445. It may also be set to a GUID to read a specific extended XMP, or 0 to ignore
  446. extended XMP entirely.
  447. 0 - ignore all extended XMP
  448. 1 - read extended XMP with valid GUID only (default)
  449. 2 - read extended XMP with any GUID
  450. <guid> - read extended XMP with a specific GUID
  451. =item ExtractEmbedded
  452. Flag to extract information from embedded documents in EPS files, embedded
  453. EPS information and JPEG and Jpeg2000 images in PDF files, embedded MPF
  454. images in JPEG and MPO files, streaming metadata in AVCHD videos, and the
  455. resource fork of Mac OS files. Default is undef.
  456. =item FastScan
  457. Flag to increase speed of extracting information from JPEG images. With
  458. this option set to 1, ExifTool will not scan to the end of a JPEG image to
  459. check for an AFCP, CanonVRD, FotoStation, PhotoMechanic, MIE or PreviewImage
  460. trailer. This also stops the parsing after the first comment in GIF images,
  461. and at the audio/video data with RIFF-format files (AVI, WAV, etc), so any
  462. trailing metadata (eg. XMP written by some utilities) may be missed. When
  463. combined with the ScanForXMP option, prevents scanning for XMP in recognized
  464. file types. With a value of 2, ExifTool will also avoid extracting any EXIF
  465. MakerNote information. When set to 3, the file is not actually parsed, and
  466. only an initial guess at FileType and some pseudo tags are returned.
  467. Default is undef.
  468. =item Filter
  469. Perl expression used to filter values for all tags. The expression acts on
  470. the value of the Perl default variable ($_), and changes the value of this
  471. variable as required. Applies to all returned values unless PrintConv
  472. option is disabled.
  473. =item FixBase
  474. Fix maker notes base offset. A common problem with image editing software
  475. is that offsets in the maker notes are not adjusted properly when the file
  476. is modified. This may cause the wrong values to be extracted for some maker
  477. note entries when reading the edited file. FixBase specifies an integer
  478. value to be added to the maker notes base offset. It may also be set to the
  479. empty string ('') for ExifTool will take its best guess at the correct base,
  480. or undef (the default) for no base adjustment.
  481. =item GeoMaxIntSecs
  482. Maximum interpolation time in seconds for geotagging. Geotagging is treated
  483. as an extrapolation if the Geotime value lies between two fixes in the same
  484. track which are separated by a number of seconds greater than this.
  485. Otherwise, the coordinates are calculated as a linear interpolation between
  486. the nearest fixes on either side of the Geotime value. Set to 0 to disable
  487. interpolation and use the coordinates of the nearest fix instead (provided
  488. it is within GeoMaxExtSecs, otherwise geotagging fails). Default is 1800.
  489. =item GeoMaxExtSecs
  490. Maximum extrapolation time in seconds for geotagging. Geotagging fails if
  491. the Geotime value lies outside a GPS track by a number of seconds greater
  492. than this. Otherwise, the coordinates of the nearest fix are taken.
  493. Default is 1800.
  494. =item GeoMaxHDOP
  495. Maximum Horizontal (2D) Dilution Of Precision for geotagging. GPS fixes are
  496. ignored if the HDOP is greater than this. Default is undef.
  497. =item GeoMaxPDOP
  498. Maximum Position (3D) Dilution Of Precision for geotagging. GPS fixes are
  499. ignored if the PDOP is greater than this. Default is undef.
  500. =item GeoMinSats
  501. Minimum number of satellites for geotagging. GPS fixes are ignored if the
  502. number of acquired satellites is less than this. Default is undef.
  503. =item GlobalTimeShift
  504. Time shift to apply to all extracted date/time PrintConv values. Does not
  505. affect ValueConv values. Value is a date/time shift string (see
  506. L<Image::ExifTool::Shift.pl|Image::ExifTool::Shift.pl>), with a leading '-'
  507. for negative shifts. Default is undef.
  508. =item Group#
  509. Extract tags only for specified groups in family # (Group0 assumed if #
  510. not given). The option value may be a single group name or a reference
  511. to a list of groups. Case is significant in group names. Specify a group
  512. to be excluded by preceding group name with a '-'. See L</GetGroup> for a
  513. description of group families, and L</GetAllGroups [static]> for lists of
  514. group names.
  515. =item HtmlDump
  516. Dump information in hex to dynamic HTML web page. The value may be 0-3 for
  517. increasingly larger limits on the maximum block size. Default is 0. Output
  518. goes to the file specified by the TextOut option (\*STDOUT by default).
  519. =item HtmlDumpBase
  520. Base for HTML dump offsets. If not defined, the EXIF/TIFF base offset is
  521. used. Set to 0 for absolute offsets. Default is undef.
  522. =item IgnoreMinorErrors
  523. Flag to ignore minor errors. Causes minor errors to be downgraded to
  524. warnings, and minor warnings to be ignored. This option is provided mainly
  525. to allow writing of files when minor errors occur, but by ignoring some
  526. minor warnings the behaviour of ExifTool may be changed to allow some
  527. questionable operations to proceed (such as extracting thumbnail and preview
  528. images even if they don't have a recognizable header). Minor errors and
  529. warnings are denoted by "[minor]" at the start of the message, or "[Minor]"
  530. (with a capital "M") for warnings that affect processing when ignored.
  531. =item Lang
  532. Localized language for exiftool tag descriptions, etc. Available languages
  533. are given by the Image::ExifTool::Lang module names (eg. 'fr', 'zh_cn'). If
  534. the specified language isn't available, the option is not changed. May be
  535. set to undef to select the built-in default language. Default is 'en'.
  536. =item LargeFileSupport
  537. Flag to indicate that 64-bit file offsets are supported on this system.
  538. Default is undef.
  539. =item List
  540. Flag to extract lists of PrintConv values into arrays instead of joining
  541. them into a string of values. The L</ListSep> option specifies the
  542. separator used when combining values. Default is undef.
  543. =item ListItem
  544. Return only a specific item from List-type values. A value of 0 returns the
  545. first item in the list, 1 return the second item, etc. Negative indices may
  546. also be used, with -1 representing the last item in the list. Applies only
  547. to the top-level list of nested lists. Default is undef to return all items
  548. in the list.
  549. =item ListSep
  550. Separator string used to join lists of PrintConv values when L</List> option
  551. is not set. Default is ', '.
  552. =item ListSplit
  553. Regular expression used to split values of list-type tags into individual
  554. items when writing. (eg. use ',\\s*' to split a comma-separated list.)
  555. Default is undef.
  556. =item MakerNotes
  557. Option to extract MakerNotes and other writable subdirectories (such as
  558. PrintIM) as a data block. Normally when the MakerNotes are extracted they
  559. are rebuilt to include data outside the boundaries of the original maker
  560. note data block, but a value of 2 disables this feature. Possible values
  561. are:
  562. 0 - Do not extract writable subdirectories (same as default of undef)
  563. 1 - Extract and rebuild maker notes into self-contained block
  564. 2 - Extract without rebuilding maker notes
  565. =item MDItemTags
  566. Flag to extract the OS X metadata item tags (see the "mdls" man page for
  567. details).
  568. =item MissingTagValue
  569. Value for missing tags in expressions evaluated by L</SetNewValuesFromFile>.
  570. If not set, a minor error is issued for missing values, or the value is set
  571. to '' if L</IgnoreMinorErrors> is set. Default is undef.
  572. =item NoPDFList
  573. Flag to avoid splitting PDF List-type tag values into separate items.
  574. Default is undef.
  575. =item Password
  576. Password for reading/writing password-protected PDF documents. Ignored if a
  577. password is not required. Character encoding of the password is determined
  578. by the value of the Charset option at processing time. Default is undef.
  579. =item PNGEarlyXMP
  580. Flag to write XMP in PNG images before the IDAT (image data) chunk. By
  581. default, ExifTool adds new XMP to the end of a PNG file (just before IEND).
  582. This is allowed by the PNG and XMP specifications, but some utilities seem
  583. to ignore XMP if it comes after the image data. The PNGEarlyXMP option
  584. causes ExifTool to instead add new XMP before the PNG IDAT chunk. However,
  585. since ExifTool uses a single-pass writing algorithm, it has no way to tell
  586. if XMP already exists later in the file before writing the new XMP in this
  587. location. If this happens, a minor error is issued when the extra XMP is
  588. encountered, and the file is not written. Adding the L</IgnoreMinorErrors>
  589. option causes the XMP after IDAT to be deleted, thus resolving the conflict
  590. (at the expense of possible metadata loss), and allowing the file to be
  591. written. The PNGEarlyXMP option is applied automatically when deleting all
  592. XMP and writing new XMP back in one step. When reading, this option causes
  593. a warning to be issued if standard XMP is found after the IDAT chunk.
  594. =item PrintConv
  595. Flag to enable automatic print conversion. Also enables inverse
  596. print conversion for writing. Default is 1.
  597. =item QuickTimeUTC
  598. Flag set to assume that QuickTime date/time values are stored as UTC,
  599. causing conversion to local time when they are extracted. According to the
  600. QuickTime specification date/time values should be UTC, but many digital
  601. cameras store local time instead (presumably because they don't know the
  602. time zone), so the default is undef. This option also disables the
  603. autodetection of incorrect time-zero offsets in QuickTime date/time values,
  604. and enforces a time zero of 1904 as per the QuickTime specification.
  605. =item RequestAll
  606. Flag to request all tags to be extracted. This causes some tags to be
  607. generated which normally would not be unless specifically requested (by
  608. passing the tag name to L</ImageInfo> or L</ExtractInfo>). Note that this
  609. flag is set automatically during a call to L</SetNewValuesFromFile> to make
  610. all tags available for copying. Default is undef.
  611. =item RequestTags
  612. List of additional tags to request in next call to L</ExtractInfo>. This
  613. option is useful only for tags which aren't extracted unless specifically
  614. requested. Value may be a list reference, a delimited string of tag names
  615. (any delimiter is allowed), or undef to clear the current RequestTags list.
  616. Case is not significant. Default is undef.
  617. =item ScanForXMP
  618. Flag to scan all files (even unrecognized formats) for XMP information
  619. unless XMP was already found in the file. When combined with the FastScan
  620. option, only unrecognized file types are scanned for XMP. Default is undef.
  621. =item Sort
  622. Specifies order to sort tags in returned list:
  623. Input - Sort in same order as input tag arguments (default)
  624. File - Sort in order that tags were found in the file
  625. Tag - Sort alphabetically by tag name
  626. Descr - Sort by tag description (for current Lang setting)
  627. Group# - Sort by tag group, where # is zero or more family
  628. numbers separated by colons. If # is not specified,
  629. Group0 is assumed. See GetGroup for a description
  630. of group families.
  631. =item Sort2
  632. Secondary sort order used for tags within each group when Sort is 'Group':
  633. File - Sort in order tags were found in the file (default)
  634. Tag - Sort alphabetically by tag name
  635. Descr - Sort by tag description (for current Lang setting)
  636. =item StrictDate
  637. Flag to return undefined value for any date which can't be converted when
  638. the DateFormat option is used. Default is undef.
  639. =item Struct
  640. Flag to return XMP structures as hash references instead of flattening into
  641. individual tags. Has no effect when writing since both flattened and
  642. structured tags may always be written. Possible values are:
  643. undef - Same as 0 for reading, 2 for copying
  644. 0 - Read/copy flattened tags
  645. 1 - Read/copy structured tags
  646. 2 - Read/copy both flattened and structured tags, but flag
  647. flattened tags as 'unsafe' for copying
  648. =item SystemTags
  649. Flag to extract the following additional File System tags: FileAttributes,
  650. FileDeviceNumber, FileInodeNumber, FileHardLinks, FileUserID, FileGroupID,
  651. FileDeviceID, FileBlockSize and FileBlockCount.
  652. =item TextOut
  653. Output file reference for Verbose and HtmlDump options. Default is
  654. \*STDOUT.
  655. =item Unknown
  656. Flag to get the values of unknown tags. If set to 1, unknown tags are
  657. extracted from EXIF (or other tagged-format) directories. If set to 2,
  658. unknown tags are also extracted from binary data blocks. Default is 0.
  659. =item UserParam
  660. Special option to set/get user-defined parameters. Useful to allow external
  661. input into tag name expressions and ValueConv logic. I<PARAM> is the
  662. user-defined parameter name (case insensitive).
  663. PARAM - Get parameter
  664. PARAM= - Clear parameter
  665. PARAM=VALUE - Set parameter
  666. User-defined parameters may be accessed in tag name expressions by prefixing
  667. the parameter name with a dollar sign, just like normal tags. If called
  668. without a parameter name, C<Options('UserParam')> returns a reference to the
  669. hash of all user parameters (with lower-case names).
  670. =item Verbose
  671. Print verbose messages to file specified by TextOut option. Value may be
  672. from 0 to 5 for increasingly verbose messages. Default is 0. With the
  673. verbose option set, messages are printed to the console as the file is
  674. parsed. Level 1 prints the tag names and raw values. Level 2 adds more
  675. details about the tags. Level 3 adds a hex dump of the tag data, but with
  676. limits on the number of bytes dumped. Levels 4 and 5 remove the dump limit
  677. on tag values and JPEG segment data respectively.
  678. =item WriteMode
  679. Set tag write/create mode. Value is a string of one or more characters from
  680. list below. Default is 'wcg'.
  681. w - Write existing tags
  682. c - Create new tags
  683. g - create new Groups as necessary
  684. The level of the group differs for different types of metadata. For XMP or
  685. IPTC this is the full XMP/IPTC block (the family 0 group), but for EXIF this
  686. is the individual IFD (the family 1 group).
  687. =item XMPAutoConv
  688. Flag to enable automatic conversion for unknown XMP tags with values that
  689. look like rational numbers or dates. Default is 1.
  690. =back
  691. =item Return Values:
  692. The original value of the last specified parameter.
  693. =back
  694. =head2 ClearOptions
  695. Reset all options to their default values. Loads user-defined default
  696. option values from the %Image::ExifTool::UserDefined::Options hash in the
  697. .ExifTool_config file if it exists.
  698. $exifTool->ClearOptions();
  699. =over 4
  700. =item Inputs:
  701. 0) ExifTool object reference
  702. =item Return Values:
  703. (none)
  704. =back
  705. =head2 ExtractInfo
  706. Extract all meta information from an image.
  707. $success = $exifTool->ExtractInfo('image.jpg', \%options);
  708. =over 4
  709. =item Inputs:
  710. L</ExtractInfo> takes exactly the same arguments as L</ImageInfo>. The only
  711. difference is that a list of tag keys is not returned if an ARRAY reference
  712. is given. The following options are effective in the call to
  713. L</ExtractInfo>:
  714. Binary, Charset, CharsetEXIF, CharsetFileName, CharsetID3, CharsetIPTC,
  715. CharsetPhotoshop, CharsetQuickTime, Composite, ExtendedXMP, ExtractEmbedded,
  716. FastScan, FixBase, HtmlDump, HtmlDumpBase, IgnoreMinorErrors, Lang,
  717. LargeFileSupport, MakerNotes, NoPDFList, PNGEarlyXMP, ScanForXMP, Struct,
  718. TextOut, Unknown and Verbose.
  719. =item Return Value:
  720. 1 if this was a recognized file format, 0 otherwise (and 'Error' tag set).
  721. =back
  722. =head2 GetInfo
  723. L</GetInfo> is called to return meta information after it has been extracted
  724. from the image by a previous call to L</ExtractInfo> or L</ImageInfo>. This
  725. function may be called repeatedly after a single call to L</ExtractInfo> or
  726. L</ImageInfo>.
  727. # get image width and height only
  728. $info = $exifTool->GetInfo('ImageWidth', 'ImageHeight');
  729. # get all Error and Warning messages
  730. $info = $exifTool->GetInfo('Error', 'Warning');
  731. # get information for all tags in list (list updated with tags found)
  732. $info = $exifTool->GetInfo(\@ioTagList);
  733. # get all information in Author or Location groups
  734. $info = $exifTool->GetInfo({Group2 => ['Author', 'Location']});
  735. =over 4
  736. =item Inputs:
  737. Inputs are the same as L</ExtractInfo> and L</ImageInfo> except that an
  738. image can not be specified. Options in effect are:
  739. Charset, CoordFormat, DateFormat, Duplicates, Escape, Exclude, Filter,
  740. Group#, GlobalTimeShift, Lang, List, ListItem, ListSep, PrintConv, Sort (if
  741. a tag list reference is given) and StrictDate.
  742. =item Return Value:
  743. Reference to information hash, the same as with L</ImageInfo>.
  744. =back
  745. =head2 WriteInfo
  746. Write meta information to a file. The specified source file is rewritten to
  747. the same-type destination file with new information as specified by previous
  748. calls to L</SetNewValue>. The necessary segments and/or directories are
  749. created in the destination file as required to store the specified
  750. information. May be called repeatedly to write the same information to
  751. additional files without the need to call L</SetNewValue> again.
  752. # add information to a source file, writing output to new file
  753. $exifTool->WriteInfo($srcfile, $dstfile);
  754. # create XMP data file from scratch
  755. $exifTool->WriteInfo(undef, $dstfile, 'XMP');
  756. # overwrite file (you do have backups, right?)
  757. $exifTool->WriteInfo($srcfile);
  758. =over 4
  759. =item Inputs:
  760. 0) ExifTool object reference
  761. 1) Source file name, file reference, scalar reference, or undef to create a
  762. file from scratch. A reference to a
  763. L<File::RandomAccess|File::RandomAccess> object is also allowed as a source,
  764. but in this case the destination is not optional.
  765. 2) [optional] Destination file name, file reference, scalar reference, or
  766. undef to overwrite the original file. May be '-' to write to stdout.
  767. 3) [optional] Destination file type. Ignored if a source is defined.
  768. =item Return Value:
  769. 1 if file was written OK, 2 if file was written but no changes made, 0 on
  770. file write error.
  771. If an error code is returned, an Error tag is set and GetValue('Error') can
  772. be called to obtain the error description. A Warning tag may be set even if
  773. this routine is successful. Calling WriteInfo clears any pre-existing Error
  774. and Warning tags.
  775. $errorMessage = $exifTool->GetValue('Error');
  776. $warningMessage = $exifTool->GetValue('Warning');
  777. =item Notes:
  778. The source file name may be undefined to create a file from scratch
  779. (currently only XMP, MIE, ICC, VRD, DR4, EXV and EXIF files can be created
  780. in this way -- see L</CanCreate> for details). If undefined, the
  781. destination file type is required unless the type can be determined from the
  782. extension of the destination file name.
  783. If a destination file name is given, the specified file must not exist
  784. because an existing destination file will not be overwritten. Any new
  785. values for FileName, Directory or HardLink are ignored when a destination
  786. file name is specified.
  787. The destination file name may be undefined to overwrite the original file
  788. (make sure you have backups!). In this case, if a source file name is
  789. provided, a temporary file is created and renamed to replace the source file
  790. if no errors occurred while writing. Otherwise, if a source file reference
  791. or scalar reference is used, the image is first written to memory then
  792. copied back to replace the original if there were no errors.
  793. On Mac OS systems, the file resource fork is preserved if this routine is
  794. called with a source file name.
  795. =back
  796. The following ExifTool options are effective in the call to L</WriteInfo>:
  797. ByteOrder, Charset, CharsetEXIF, CharsetFileName, CharsetIPTC, Compact,
  798. Compress, FixBase, IgnoreMinorErrors, PNGEarlyXMP and Verbose.
  799. =head2 GetTagList
  800. Get a sorted list of tags from the specified information hash or tag list.
  801. @tags = $exifTool->GetTagList($info, 'Group0');
  802. =over 4
  803. =item Inputs:
  804. 0) ExifTool object reference
  805. 1) [optional] Information hash reference or tag list reference
  806. 2) [optional] Sort order ('Input', 'File', 'Tag', 'Descr' or 'Group#')
  807. 3) [optional] Secondary sort order ('File', 'Tag' or 'Descr')
  808. If the information hash or tag list reference is not provided, then the list
  809. of found tags from the last call to L</ImageInfo>, L</ExtractInfo> or
  810. L</GetInfo> is used instead, and the result is the same as if
  811. L</GetFoundTags> was called. If sort order is not specified, the sort order
  812. is taken from the current options settings.
  813. =item Return Values:
  814. A list of tag keys in the specified order.
  815. =back
  816. =head2 GetFoundTags
  817. Get list of found tags in specified sort order. The found tags are the tags
  818. for the information obtained from the most recent call to L</ImageInfo>,
  819. L</ExtractInfo> or L</GetInfo> for this object.
  820. @tags = $exifTool->GetFoundTags('File');
  821. =over 4
  822. =item Inputs:
  823. 0) ExifTool object reference
  824. 1) [optional] Sort order ('Input', 'File', 'Tag', 'Descr' or 'Group#')
  825. 2) [optional] Secondary sort order ('File', 'Tag' or 'Descr')
  826. If sort order is not specified, the sort order from the ExifTool options is
  827. used.
  828. =item Return Values:
  829. A list of tag keys in the specified order.
  830. =back
  831. =head2 GetRequestedTags
  832. Get list of requested tags. These are the tags that were specified in the
  833. arguments of the most recent call to L</ImageInfo>, L</ExtractInfo> or
  834. L</GetInfo>, including tags specified via a tag list reference. Shortcut
  835. tags are expanded in the list.
  836. @tags = $exifTool->GetRequestedTags();
  837. =over 4
  838. =item Inputs:
  839. (none)
  840. =item Return Values:
  841. List of requested tag keys in the same order that the tags were specified.
  842. Note that this list will be empty if tags were not specifically requested
  843. (ie. If extracting all tags).
  844. =back
  845. =head2 GetValue
  846. Get the value of a specified tag. The returned value is either the
  847. human-readable (PrintConv) value, the converted machine-readable (ValueConv)
  848. value, or the original raw (Raw) value. If the value type is not specified,
  849. the PrintConv value is returned if the PrintConv option is set, otherwise
  850. the ValueConv value is returned. The PrintConv values are same as the
  851. values returned by L</ImageInfo> and L</GetInfo> in the tag/value hash
  852. unless the PrintConv option is disabled.
  853. Tags which represent lists of multiple values (as may happen with 'Keywords'
  854. for example) are handled specially. In scalar context, the returned
  855. PrintConv value for these tags is either a string of values or a list
  856. reference (depending on the List option setting), and the ValueConv value is
  857. always a list reference. But in list context, L</GetValue> always returns
  858. the list itself.
  859. Note that L</GetValue> requires a case-sensitive tag key as an argument. To
  860. retrieve tag information based on a case-insensitive tag name (with an
  861. optional group specifier), use L</GetInfo> instead.
  862. # PrintConv example
  863. my $val = $exifTool->GetValue($tag);
  864. if (ref $val eq 'SCALAR') {
  865. print "$tag = (unprintable value)\n";
  866. } else {
  867. print "$tag = $val\n";
  868. }
  869. # ValueConv examples
  870. my $val = $exifTool->GetValue($tag, 'ValueConv');
  871. if (ref $val eq 'ARRAY') {
  872. print "$tag is a list of values\n";
  873. } elsif (ref $val eq 'SCALAR') {
  874. print "$tag represents binary data\n";
  875. } else {
  876. print "$tag is a simple scalar\n";
  877. }
  878. my @keywords = $exifTool->GetValue('Keywords', 'ValueConv');
  879. The following options are in effect when L</GetValue> is called:
  880. Charset, CoordFormat, DateFormat, Escape, Filter, GlobalTimeShift, Lang,
  881. List, ListItem, ListSep, PrintConv and StrictDate.
  882. =over 4
  883. =item Inputs:
  884. 0) ExifTool object reference
  885. 1) Tag key
  886. 2) [optional] Value type: 'PrintConv', 'ValueConv', 'Both', 'Raw' or
  887. 'Rational'
  888. The default value type is 'PrintConv' if the PrintConv option is set,
  889. otherwise the default is 'ValueConv'. A value type of 'Both' returns both
  890. ValueConv and PrintConv values as a list. 'Rational' returns the raw
  891. rational value as a string fraction for rational types, or undef for other
  892. types.
  893. =item Return Values:
  894. The value of the specified tag. If the tag represents a list of multiple
  895. values and the List option is disabled then PrintConv returns a string of
  896. values, otherwise a reference to the list is returned in scalar context.
  897. The list itself is returned in list context. (Unless 'Both' values are
  898. requested, in which case two list references are returned, regardless of
  899. context.) Values may also be scalar references to binary data, or hash
  900. references if the L</Struct> option is set.
  901. Note: It is possible for L</GetValue> to return an undefined ValueConv or
  902. PrintConv value (or an empty list in list context) even if the tag exists,
  903. since it is possible for these conversions to yield undefined values. And
  904. the Rational value will be undefined for any non-rational tag. The Raw
  905. value should always exist if the tag exists.
  906. =back
  907. =head2 SetNewValue
  908. Set the new value for a tag. The routine may be called multiple times to
  909. set the values of many tags before using L</WriteInfo> to write the new
  910. values to an image.
  911. For list-type tags (like Keywords), either call repeatedly with the same tag
  912. name for each value, or call with a reference to the list of values.
  913. # set a new value for a tag (errors go to STDERR)
  914. $success = $exifTool->SetNewValue($tag, $value);
  915. # set a new value and capture any error message
  916. ($success, $errStr) = $exifTool->SetNewValue($tag, $value);
  917. # delete information for specified tag if it exists in image
  918. # (also resets AddValue and DelValue options for this tag)
  919. $exifTool->SetNewValue($tag);
  920. # reset all values from previous calls to SetNewValue()
  921. $exifTool->SetNewValue();
  922. # delete a specific keyword
  923. $exifTool->SetNewValue('Keywords', $word, DelValue => 1);
  924. # set keywords (a list-type tag) with two new values
  925. $exifTool->SetNewValue(Keywords => 'word1');
  926. $exifTool->SetNewValue(Keywords => 'word2');
  927. # equivalent, but set both in one call using an array reference
  928. $exifTool->SetNewValue(Keywords => ['word1','word2']);
  929. # add a keyword without replacing existing keywords in the file
  930. $exifTool->SetNewValue(Keywords => $word, AddValue => 1);
  931. # set a tag in a specific group
  932. $exifTool->SetNewValue(Headline => $val, Group => 'XMP');
  933. $exifTool->SetNewValue('XMP:Headline' => $val); # (equivalent)
  934. # shift original date/time back by 2.5 hours
  935. $exifTool->SetNewValue(DateTimeOriginal => '2:30', Shift => -1);
  936. # write a tag only if it had a specific value
  937. # (the order of the following calls is not significant)
  938. $exifTool->SetNewValue(Title => $oldVal, DelValue => 1);
  939. $exifTool->SetNewValue(Title => $newVal);
  940. # write tag by numerical value
  941. $exifTool->SetNewValue(Orientation => 6, Type => 'ValueConv');
  942. $exifTool->SetNewValue('Orientation#' => 6); # (equivalent)
  943. # delete all but EXIF tags
  944. $exifTool->SetNewValue('*'); # delete all...
  945. $exifTool->SetNewValue('EXIF:*', undef, Replace => 2); # ...but EXIF
  946. # write structured information as a HASH reference
  947. $exifTool->SetNewValue('XMP:Flash' => {
  948. mode => 'on',
  949. fired => 'true',
  950. return => 'not'
  951. });
  952. # write structured information as a serialized string
  953. $exifTool->SetNewValue('XMP:Flash'=>'{mode=on,fired=true,return=not}');
  954. (See L<http://owl.phy.queensu.ca/~phil/exiftool/struct.html#Serialize> for
  955. a description of the structure serialization technique.)
  956. =over 4
  957. =item Inputs:
  958. 0) ExifTool object reference
  959. 1) [optional] Tag key or tag name, or undef to clear all new values. The
  960. tag name may be prefixed by one or more family 0, 1 or 2 group names with
  961. optional leading family numbers, separated by colons (eg. 'EXIF:Artist',
  962. 'XMP:Time:*'), which is equivalent to using a Group option argument. Also,
  963. a '#' may be appended to the tag name (eg. 'EXIF:Orientation#'), with the
  964. same effect as setting Type to 'ValueConv'. Wildcards ('*' and '?') may be
  965. used in the tag name to assign multiple tags simultaneously. A tag name of
  966. '*' is special when deleting information, and will delete an entire group
  967. even if some individual tags in the group are not writable, but only if a
  968. single family 0 or 1 group is specified (otherwise the tags are deleted
  969. individually). Use L</GetDeleteGroups> to get a list of deletable group
  970. names, and see L<Image::ExifTool::TagNames|Image::ExifTool::TagNames> for a
  971. complete list of tag names.
  972. 2) [optional] New value for tag. Undefined to delete tag from file. May be
  973. a scalar, scalar reference, list reference to set a list of values, or hash
  974. reference for a structure. Integer values may be specified as a hexadecimal
  975. string (with a leading '0x'), and simple rational values may be specified in
  976. fractional form (eg. '4/10'). Structure tags may be specified either as a
  977. hash reference or a serialized string (see the last two examples above).
  978. 3-N) [optional] SetNewValue option/value pairs (see below).
  979. =item SetNewValue Options:
  980. =over 4
  981. =item AddValue
  982. Specifies that the value be added to an existing list in a file rather than
  983. overwriting. Valid settings are 0 (overwrite any existing tag value), 1
  984. (add to an existing list and warn for non-list tags) or 2 (add to existing
  985. list and overwrite non-list tags). Default is 0.
  986. =item DelValue
  987. Delete existing tag from a file if it has the specified value. Option
  988. values are 0 or 1. Default is 0.
  989. =item EditGroup
  990. Create tags in existing groups only. Don't create new group. Valid values
  991. are 0 and 1. Effectively removes the 'g' from the ExifTool WriteMode option
  992. for this tag only. Default is 0.
  993. =item EditOnly
  994. Edit tag only if it already exists. Don't create new tag. Valid values are
  995. 0 and 1. Effectively removes the 'c' from the ExifTool WriteMode option for
  996. this tag only. Default is 0.
  997. =item Group
  998. Specifies group name where tag should be written. If not specified, tag is
  999. written to highest priority group as specified by L</SetNewGroups>. May be
  1000. one or more family 0, 1 or 2 groups with optional leading family number,
  1001. separated by colons. Case is not significant.
  1002. =item NoFlat
  1003. Treat flattened tags as 'unsafe'.
  1004. =item NoShortcut
  1005. Disables default behaviour of looking up tag in shortcuts if not found
  1006. otherwise.
  1007. =item Protected
  1008. Bit mask for tag protection levels to write. Bit 0x01 allows writing of
  1009. 'unsafe' tags (ie. tags not copied automatically via
  1010. L</SetNewValuesFromFile>). Bit 0x02 allows writing of 'protected' tags, and
  1011. should only be used internally by ExifTool. See
  1012. L<Image::ExifTool::TagNames|Image::ExifTool::TagNames>, for a list of tag
  1013. names indicating 'unsafe' and 'protected' tags. Default is 0.
  1014. =item ProtectSaved
  1015. Avoid setting new values which were saved after the Nth call to
  1016. L</SaveNewValues>. Has no effect on unsaved values, or values saved before
  1017. Nth call. Option value is N. Default is undef.
  1018. =item Replace
  1019. Flag to replace the previous new values for this tag (ie. replace the values
  1020. set in previous calls to L</SetNewValue>). This option is most commonly
  1021. used to replace previously-set new values for list-type tags. Valid values
  1022. are 0 (set new value normally -- adds to new values for list-type tags), 1
  1023. (reset previous new values for this tag and replace with the specified new
  1024. value) or 2 (reset previous new values only).
  1025. =item Shift
  1026. Shift the tag by the specified value. Currently only date/time tags and
  1027. tags with numerical values may be shifted. Undefined for no shift, 1 for a
  1028. positive shift, or -1 for a negative shift. A value of 0 causes a positive
  1029. shift to be applied if the tag is shiftable and AddValue is set, or a
  1030. negative shift for date/time tags only if DelValue is set. Default is undef.
  1031. See L<Image::ExifTool::Shift.pl|Image::ExifTool::Shift.pl> for more
  1032. information.
  1033. =item Type
  1034. The type of value being set. Valid values are PrintConv, ValueConv or Raw.
  1035. Default is PrintConv if the L</PrintConv> Option is set, otherwise
  1036. ValueConv.
  1037. =back
  1038. =item Return Values:
  1039. In scalar context, returns the number of tags set and error messages are
  1040. printed to STDERR. In list context, returns the number of tags set, and the
  1041. error string (which is undefined if there was no error).
  1042. =item Notes:
  1043. When deleting groups of tags, the Replace option may be used to exclude
  1044. specific groups from a mass delete. However, this technique may not be used
  1045. to exclude individual tags from a group delete (unless a family 2 group was
  1046. specified in the delete). Instead, use L</SetNewValuesFromFile> to recover
  1047. the values of individual tags after deleting a group.
  1048. When deleting all tags from a JPEG image, the APP14 "Adobe" information is
  1049. not deleted by default because doing so may affect the appearance of the
  1050. image. However, this information may be deleted by specifying it
  1051. explicitly, either by group (with 'Adobe:*') or as a block (with 'Adobe').
  1052. =back
  1053. The following ExifTool options are effective in the call to L</SetNewValue>:
  1054. Charset, Escape, IgnoreMinorErrors, Lang, ListSep, ListSplit, PrintConv,
  1055. Verbose and WriteMode.
  1056. =head2 GetNewValue
  1057. Get the new Raw value for a tag. This is the value set by L</SetNewValue>
  1058. this is queued to be written to file. List-type tags may return multiple
  1059. values in list context.
  1060. $rawVal = $exifTool->GetNewValue($tag);
  1061. @rawVals = $exifTool->GetNewValue($tag);
  1062. =over 4
  1063. =item Inputs:
  1064. 0) ExifTool object reference
  1065. 1) Tag name (case sensitive, may be prefixed by family 0 or 1 group name)
  1066. =item Return Values:
  1067. List of new Raw tag values, or first value in list when called in scalar
  1068. context. The list may be empty either if the tag isn't being written, or if
  1069. it is being deleted (ie. if L</SetNewValue> was called without a value).
  1070. =back
  1071. =head2 SetNewValuesFromFile
  1072. A very powerful routine that sets new values for tags from information found
  1073. in a specified file.
  1074. # set new values from all information in a file...
  1075. my $info = $exifTool->SetNewValuesFromFile($srcFile);
  1076. # ...then write these values to another image
  1077. my $result = $exifTool->WriteInfo($file2, $outFile);
  1078. # set all new values, preserving original groups
  1079. $exifTool->SetNewValuesFromFile($srcFile, '*:*');
  1080. # set specific information
  1081. $exifTool->SetNewValuesFromFile($srcFile, @tags);
  1082. # set new value from a different tag in specific group
  1083. $exifTool->SetNewValuesFromFile($fp, 'IPTC:Keywords>XMP-dc:Subject');
  1084. # add all IPTC keywords to XMP subject list
  1085. $exifTool->SetNewValuesFromFile($fp, 'IPTC:Keywords+>XMP-dc:Subject');
  1086. # set new value from an expression involving other tags
  1087. $exifTool->SetNewValuesFromFile($file,
  1088. 'Comment<ISO=$ISO Aperture=$aperture Exposure=$shutterSpeed');
  1089. # set keywords list from the values of multiple tags
  1090. $exifTool->SetNewValuesFromFile($file, { Replace => 0 },
  1091. 'keywords<xmp:subject', 'keywords<filename');
  1092. # copy all EXIF information, preserving the original IFD
  1093. # (without '>*.*' tags would be copied to the preferred EXIF IFD)
  1094. $exifTool->SetNewValuesFromFile($file, 'EXIF:*>*:*');
  1095. # copy all tags with names starting with "gps" (note: this is
  1096. # different than "gps:*" because it will also copy XMP GPS tags)
  1097. $exifTool->SetNewValuesFromFile($file, 'gps*');
  1098. # set FileName from Model, translating questionable characters
  1099. $exifTool->SetNewValuesFromFile($file,
  1100. 'filename<${model; tr(/\\\\?*:|"><)(_) }.jpg');
  1101. =over 4
  1102. =item Inputs:
  1103. 0) ExifTool object reference
  1104. 1) File name, file reference, or scalar reference
  1105. 2-N) [optional] List of tag names to set or options hash references. All
  1106. writable tags are set if none are specified. The tag names are not case
  1107. sensitive, and may be prefixed by one or more family 0, 1 or 2 group names with
  1108. optional leading family numbers, separated by colons (eg. 'exif:iso'). A
  1109. leading '-' indicates tags to be excluded (eg. '-comment'), or a trailing '#'
  1110. causes the ValueConv value to be copied (same as setting the Type option to
  1111. 'ValueConv' for this tag only). Wildcards ('*' and '?') may be used in the tag
  1112. name. A tag name of '*' is commonly used when a group is specified to copy all
  1113. tags in the group (eg. 'XMP:*'). A special feature allows tag names of the form
  1114. 'DSTTAGE<lt>SRCTAG' (or 'SRCTAGE<gt>DSTTAG') to be specified to copy information
  1115. to a tag with a different name or a specified group. Both 'SRCTAG' and 'DSTTAG'
  1116. may contain wildcards and/or be prefixed by a group name (eg.
  1117. 'fileModifyDateE<lt>modifyDate' or 'xmp:*E<lt>*'), and/or suffixed by a '#' to
  1118. disable print conversion. Copied tags may also be added or deleted from a list
  1119. with arguments of the form 'DSTTAG+E<lt>SRCTAG' or 'DSTTAG-E<lt>SRCTAG'. Tags
  1120. are evaluated in order, so exclusions apply only to tags included earlier in the
  1121. list. An extension of this feature allows the tag value to be set from an
  1122. expression containing tag names with leading '$' symbols (eg. 'CommentE<lt>the
  1123. file is $filename'). Braces '{}' may be used around the tag name to separate it
  1124. from subsequent text, and a '$$' is used to to represent a '$' symbol. The
  1125. behaviour for missing tags in expressions is defined by the L</MissingTagValue>
  1126. option. The tag value may be modified via changes to the default input variable
  1127. ($_) in Perl expressions placed inside the braces and after a semicolon
  1128. following the tag name. Braces within the expression must be balanced.
  1129. Multiple options hash references may be passed to set different options for
  1130. different tags. Options apply to subsequent tags in the argument list.
  1131. By default, this routine will commute information between same-named tags in
  1132. different groups, allowing information to be translated between images with
  1133. different formats. This behaviour may be modified by specifying a group
  1134. name for extracted tags (even if '*' is used as a group name), in which case
  1135. the information is written to the original group, unless redirected to a
  1136. different group. When '*' is used for a group name, by default the family 1
  1137. group of the original tag is preserved, but a different family may be specified
  1138. with a leading family number. (For example, specifying '*:*' copies all
  1139. information while preserving the original family 1 groups, while '0*:*'
  1140. preserves the family 0 group.)
  1141. =item SetNewValuesFromFile Options:
  1142. The options are the same was for L</SetNewValue>, and are passed directly
  1143. to L</SetNewValue> internally, with a few exceptions:
  1144. - The Replace option defaults to 1 instead of 0 as with L</SetNewValue>.
  1145. - The AddValue or DelValue option is set for individual tags if '+>' or '->'
  1146. (or '+E<lt>' or '-E<lt>') are used.
  1147. - The Group option is set for tags where a group name is given.
  1148. - The Protected flag is set to 1 for individually specified tags.
  1149. - The Type option also applies to extracted tags.
  1150. =item Return Values:
  1151. A hash of information that was set successfully. May include Warning or
  1152. Error entries if there were problems reading the input file.
  1153. =item Notes:
  1154. The PrintConv option applies to this routine, but it normally should be left
  1155. on to provide more reliable transfer of information between groups.
  1156. If a preview image exists, it is not copied. The preview image must be
  1157. transferred separately if desired, in a separate call to L</WriteInfo>
  1158. When simply copying all information between files of the same type, it is
  1159. usually desirable to preserve the original groups by specifying '*:*' for
  1160. the tags to set.
  1161. The L</Duplicates> option is always in effect for tags extracted from the
  1162. source file using this routine.
  1163. The L</Struct> option is enabled by default for tags extracted by this
  1164. routine. This allows the hierarchy of complex structures to be preserved
  1165. when copying, but the Struct option may be set to 0 to override this
  1166. behaviour and copy as flattened tags instead.
  1167. =back
  1168. =head2 CountNewValues
  1169. Return the total number of new values set.
  1170. $numSet = $exifTool->CountNewValues();
  1171. ($numSet, $numPseudo) = $exifTool->CountNewValues();
  1172. =over 4
  1173. =item Inputs:
  1174. 0) ExifTool object reference
  1175. =item Return Values:
  1176. In scalar context, returns the total number of tags with new values set. In
  1177. list context, also returns the number of "pseudo" tag values which have been
  1178. set. "Pseudo" tags are tags like FileName and FileModifyDate which are not
  1179. contained within the file and can be changed without rewriting the file.
  1180. =back
  1181. =head2 SaveNewValues
  1182. Save state of new values to be later restored by L</RestoreNewValues>.
  1183. $exifTool->SaveNewValues(); # save state of new values
  1184. $exifTool->SetNewValue(ISO => 100); # set new value for ISO
  1185. $exifTool->WriteInfo($src, $dst1); # write ISO + previous new values
  1186. $exifTool->RestoreNewValues(); # restore previous new values
  1187. $exifTool->WriteInfo($src, $dst2); # write previous new values only
  1188. =over 4
  1189. =item Inputs:
  1190. 0) ExifTool object reference
  1191. =item Return Value:
  1192. Count of the number of times this routine has been called (N) since the last
  1193. time the new values were reset.
  1194. =back
  1195. =head2 RestoreNewValues
  1196. Restore new values to the settings that existed when L</SaveNewValues> was
  1197. last called. May be called repeatedly after a single call to
  1198. L</SaveNewValues>. See L</SaveNewValues> above for an example.
  1199. =over 4
  1200. =item Inputs:
  1201. 0) ExifTool object reference
  1202. =item Return Value:
  1203. None.
  1204. =back
  1205. =head2 SetFileModifyDate
  1206. Write the filesystem modification or creation time from the new value of the
  1207. FileModifyDate or FileCreateDate tag.
  1208. $exifTool->SetNewValue(FileModifyDate => '2000:01:02 03:04:05-05:00',
  1209. Protected => 1);
  1210. $result = $exifTool->SetFileModifyDate($file);
  1211. =over 4
  1212. =item Inputs:
  1213. 0) ExifTool object reference
  1214. 1) File name
  1215. 2) [optional] Base time if applying shift (days before $^T)
  1216. 3) [optional] Tag to write: 'FileModifyDate' (default), or 'FileCreateDate'
  1217. =item Return Value:
  1218. 1 if the time was changed, 0 if nothing was done, or -1 if there was an
  1219. error setting the time.
  1220. =item Notes:
  1221. Equivalent to, but more efficient than calling L</WriteInfo> when only the
  1222. FileModifyDate or FileCreateDate tag has been set. If a timezone is not
  1223. specified, local time is assumed. When shifting, the time of the original
  1224. file is used unless the optional base time is specified.
  1225. The ability to write FileCreateDate is currently restricted to Windows
  1226. systems only.
  1227. =back
  1228. =head2 SetFileName
  1229. Set the file name and directory, or create a hard link. If not specified,
  1230. the new file name is derived from the new values of the FileName and
  1231. Directory tags, or from the HardLink tag if creating a link. If the
  1232. FileName tag contains a '/', then the file is renamed into a new directory.
  1233. If FileName ends with '/', then it is taken as a directory name and the file
  1234. is moved into the new directory. The new value for the Directory tag takes
  1235. precedence over any directory specified in FileName.
  1236. $result = $exifTool->SetFileName($file);
  1237. $result = $exifTool->SetFileName($file, $newName);
  1238. =over 4
  1239. =item Inputs:
  1240. 0) ExifTool object reference
  1241. 1) Current file name
  1242. 2) [optional] New file name
  1243. 3) [optional] 'Link' to create a hard link instead of renaming the file, or
  1244. 'Test' to test renaming feature by printing the old and new names instead of
  1245. changing anything.
  1246. =item Return Value:
  1247. 1 if the file name or directory was changed, 0 if nothing was done, or -1 if
  1248. there was an error renaming the file.
  1249. =item Notes:
  1250. Will not overwrite existing files. New directories are created as necessary.
  1251. =back
  1252. =head2 SetNewGroups
  1253. Set the order of the preferred groups when adding new information. In
  1254. subsequent calls to L</SetNewValue>, new information will be created in the
  1255. first valid group of this list. This has an impact only if the group is not
  1256. specified when calling L</SetNewValue> and if the tag name exists in more
  1257. than one group. The default order is EXIF, IPTC then XMP. Any family 0
  1258. group name may be used. Case is not significant.
  1259. $exifTool->SetNewGroups('XMP','EXIF','IPTC');
  1260. =over 4
  1261. =item Inputs:
  1262. 0) ExifTool object reference
  1263. 1-N) Groups in order of priority. If no groups are specified, the priorities
  1264. are reset to the defaults.
  1265. =item Return Value:
  1266. None.
  1267. =back
  1268. =head2 GetNewGroups
  1269. Get current group priority list.
  1270. @groups = $exifTool->GetNewGroups();
  1271. =over 4
  1272. =item Inputs:
  1273. 0) ExifTool object reference
  1274. =item Return Values:
  1275. List of group names in order of write priority. Highest priority first.
  1276. =back
  1277. =head2 GetTagID
  1278. Get the ID for the specified tag. The ID is the IFD tag number in EXIF
  1279. information, the property name in XMP information, or the data offset in a
  1280. binary data block. For some tags, such as Composite tags where there is no
  1281. ID, an empty string is returned. In list context, also returns a language
  1282. code for the tag if available and different from the default language (eg.
  1283. with alternate language entries for XMP "lang-alt" tags).
  1284. $id = $exifTool->GetTagID($tag);
  1285. ($id, $lang) = $exifTool->GetTagID($tag);
  1286. =over 4
  1287. =item Inputs:
  1288. 0) ExifTool object reference
  1289. 1) Tag key
  1290. =item Return Values:
  1291. In scalar context, returns the tag ID or '' if there is no ID for this tag.
  1292. In list context, returns the tag ID (or '') and the language code (or
  1293. undef).
  1294. =back
  1295. =head2 GetDescription
  1296. Get description for specified tag. This function will always return a
  1297. defined value. In the case where the description doesn't exist, one is
  1298. generated from the tag name.
  1299. =over 4
  1300. =item Inputs:
  1301. 0) ExifTool object reference
  1302. 1) Tag key
  1303. =item Return Values:
  1304. A description for the specified tag.
  1305. =back
  1306. =head2 GetGroup
  1307. Get group name(s) for a specified tag.
  1308. # return family 0 group name (eg. 'EXIF');
  1309. $group = $exifTool->GetGroup($tag, 0);
  1310. # return all groups (eg. qw{EXIF IFD0 Author Main})
  1311. @groups = $exifTool->GetGroup($tag);
  1312. # return groups as a string (eg. 'Main:IFD0:Author')
  1313. $group = $exifTool->GetGroup($tag, ':3:1:2');
  1314. # return groups as a simplified string (eg. 'IFD0:Author')
  1315. $group = $exifTool->GetGroup($tag, '3:1:2');
  1316. =over 4
  1317. =item Inputs:
  1318. 0) ExifTool object reference
  1319. 1) Tag key
  1320. 2) [optional] Group family number, or string of numbers separated by colons
  1321. =item Return Values:
  1322. Group name (or '' if tag has no group). If no group family is specified,
  1323. L</GetGroup> returns the name of the group in family 0 when called in scalar
  1324. context, or the names of groups for all families in list context. Returns a
  1325. string of group names separated by colons if the input group family contains
  1326. a colon. The string is simplified to remove a leading 'Main:' and adjacent
  1327. identical group names unless the family string begins with a colon.
  1328. =item Notes:
  1329. The group family numbers are currently available:
  1330. 0) Information Type (eg. EXIF, XMP, IPTC)
  1331. 1) Specific Location (eg. IFD0, XMP-dc)
  1332. 2) Category (eg. Author, Time)
  1333. 3) Document Number (eg. Main, Doc1, Doc3-2)
  1334. 4) Instance Number (eg. Copy1, Copy2, Copy3...)
  1335. Families 0 and 1 are based on the file structure, and are similar except
  1336. that family 1 is more specific and sub-divides some groups to give more
  1337. detail about the specific location where the information was found. For
  1338. example, the EXIF group is split up based on the specific IFD (Image File
  1339. Directory), the MakerNotes group is divided into groups for each
  1340. manufacturer, and the XMP group is separated based on the XMP namespace
  1341. prefix. Note that only common XMP namespaces are listed in the
  1342. L<GetAllGroups documentation|/GetAllGroups [static]>, but additional
  1343. namespaces may be present in some XMP data. Also note that the 'XMP-xmp...'
  1344. group names may appear in the older form 'XMP-xap...' since these names
  1345. evolved as the XMP standard was developed. The ICC_Profile group is broken
  1346. down to give information about the specific ICC_Profile tag from which
  1347. multiple values were extracted. As well, information extracted from the
  1348. ICC_Profile header is separated into the ICC-header group.
  1349. Family 2 classifies information based on the logical category to which the
  1350. information refers.
  1351. Family 3 gives the document number for tags extracted from embedded
  1352. documents, or 'Main' for tags from the main document. (See the
  1353. L</ExtractEmbedded> option for extracting tags from embedded documents.)
  1354. Nested sub-documents (if they exist) are indicated by numbers separated with
  1355. dashes in the group name, to an arbitrary depth. (eg. 'Doc2-3-1' is the 1st
  1356. sub-sub-document of the 3rd sub-document of the 2nd embedded document of the
  1357. main file.)
  1358. Family 4 provides a method for differentiating tags when multiple tags exist
  1359. with the same name in the same location. The primary instance of a tag (the
  1360. tag extracted when the Duplicates option is disabled and no group is
  1361. specified) has no family 4 group name, but additional instances have have
  1362. family 4 group names of 'Copy1', 'Copy2', 'Copy3', etc.
  1363. See L</GetAllGroups [static]> for complete lists of group names.
  1364. =back
  1365. =head2 GetGroups
  1366. Get list of group names that exist in the specified information.
  1367. @groups = $exifTool->GetGroups($info, 2);
  1368. @groups = $exifTool->GetGroups('3:1');
  1369. =over 4
  1370. =item Inputs:
  1371. 0) ExifTool object reference
  1372. 1) [optional] Info hash ref (default is all extracted info)
  1373. 2) [optional] Group family number, or string of numbers (default 0)
  1374. =item Return Values:
  1375. List of group names in alphabetical order. If information hash is not
  1376. specified, the group names are returned for all extracted information. See
  1377. L</GetGroup> for an description of family numbers and family number strings.
  1378. =back
  1379. =head2 BuildCompositeTags
  1380. Builds composite tags from required tags. The composite tags are
  1381. convenience tags which are derived from the values of other tags. This
  1382. routine is called automatically by L</ImageInfo> and L</ExtractInfo> if the
  1383. Composite option is set.
  1384. =over 4
  1385. =item Inputs:
  1386. 0) ExifTool object reference
  1387. =item Return Values:
  1388. (none)
  1389. =item Notes:
  1390. Tag values are calculated in alphabetical order unless a tag Require's or
  1391. Desire's another composite tag, in which case the calculation is deferred
  1392. until after the other tag is calculated.
  1393. Composite tags may need to read data from the image for their value to be
  1394. determined, and for these L</BuildCompositeTags> must be called while the
  1395. image is available. This is only a problem if L</ImageInfo> is called with
  1396. a filename (as opposed to a file reference or scalar reference) since in
  1397. this case the file is closed before L</ImageInfo> returns. Here the
  1398. Composite option may be used so that L</BuildCompositeTags> is called from
  1399. within L</ImageInfo>, before the file is closed.
  1400. =back
  1401. =head2 GetTagName [static]
  1402. Get name of tag from tag key. This is a convenience function that
  1403. strips the embedded instance number, if it exists, from the tag key.
  1404. Note: "static" in the heading above indicates that the function does not
  1405. require an ExifTool object reference as the first argument. All functions
  1406. documented below are also static.
  1407. $tagName = Image::ExifTool::GetTagName($tag);
  1408. =over 4
  1409. =item Inputs:
  1410. 0) Tag key
  1411. =item Return Value:
  1412. Tag name. This is the same as the tag key but has the instance number
  1413. removed.
  1414. =back
  1415. =head2 GetShortcuts [static]
  1416. Get a list of shortcut tags.
  1417. =over 4
  1418. =item Inputs:
  1419. (none)
  1420. =item Return Values:
  1421. List of shortcut tags (as defined in Image::ExifTool::Shortcuts).
  1422. =back
  1423. =head2 GetAllTags [static]
  1424. Get list of all available tag names.
  1425. @tagList = Image::ExifTool::GetAllTags($group);
  1426. =over 4
  1427. =item Inputs:
  1428. 0) [optional] Group name, or string of group names separated by colons
  1429. =item Return Values:
  1430. A list of all available tags in alphabetical order, or all tags in a
  1431. specified group or intersection of groups. The group name is case
  1432. insensitive, and any group in families 0-2 may be used except for EXIF
  1433. family 1 groups (ie. the specific IFD).
  1434. =back
  1435. =head2 GetWritableTags [static]
  1436. Get list of all writable tag names.
  1437. @tagList = Image::ExifTool::GetWritableTags($group);
  1438. =over 4
  1439. =item Inputs:
  1440. 0) [optional] Group name, or string of group names separated by colons
  1441. =item Return Values:
  1442. A list of all writable tags in alphabetical order. These are the tags for
  1443. which values may be set through L</SetNewValue>. If a group name is given,
  1444. returns only writable tags in specified group(s). The group name is case
  1445. insensitive, and any group in families 0-2 may be used except for EXIF
  1446. family 1 groups (ie. the specific IFD).
  1447. =back
  1448. =head2 GetAllGroups [static]
  1449. Get list of all group names in specified family.
  1450. @groupList = Image::ExifTool::GetAllGroups($family);
  1451. =over 4
  1452. =item Inputs:
  1453. 0) Group family number (0-4)
  1454. =item Return Values:
  1455. A list of all groups in the specified family in alphabetical order.
  1456. =back
  1457. Here is a complete list of groups for each of these families:
  1458. =over 4
  1459. =item Family 0 (Information Type):
  1460. AFCP, AIFF, APE, APP0, APP1, APP11, APP12, APP13, APP14, APP15, APP4, APP5,
  1461. APP6, APP8, ASF, Audible, CanonVRD, Composite, DICOM, DNG, DV, DjVu, Ducky,
  1462. EXE, EXIF, ExifTool, FLAC, FLIR, File, Flash, FlashPix, Font, FotoStation,
  1463. GIF, GIMP, GeoTiff, H264, HTML, ICC_Profile, ID3, IPTC, ITC, JFIF, JPEG,
  1464. Jpeg2000, LNK, Leaf, Lytro, M2TS, MIE, MIFF, MNG, MOI, MPC, MPEG, MPF, MXF,
  1465. MakerNotes, Matroska, Meta, Ogg, OpenEXR, PDF, PICT, PLIST, PNG, PSP, Palm,
  1466. PanasonicRaw, PhotoCD, PhotoMechanic, Photoshop, PostScript, PrintIM,
  1467. QuickTime, RAF, RIFF, RSRC, RTF, Radiance, Rawzor, Real, SVG, SigmaRaw,
  1468. Stim, Theora, Torrent, VCard, Vorbis, XML, XMP, ZIP
  1469. =item Family 1 (Specific Location):
  1470. AC3, AFCP, AIFF, APE, ASF, AVI1, Adobe, AdobeCM, AdobeDNG, Apple, Audible,
  1471. CIFF, Canon, CanonCustom, CanonRaw, CanonVRD, Casio, Chapter#, Composite,
  1472. DICOM, DNG, DV, DjVu, DjVu-Meta, Ducky, EPPIM, EXE, EXIF, ExifIFD, ExifTool,
  1473. FLAC, FLIR, File, Flash, FlashPix, Font, FotoStation, FujiFilm, FujiIFD, GE,
  1474. GIF, GIMP, GPS, GeoTiff, GlobParamIFD, GraphConv, H264, HP, HTC, HTML,
  1475. HTML-dc, HTML-ncc, HTML-office, HTML-prod, HTML-vw96, HTTP-equiv, ICC-chrm,
  1476. ICC-clrt, ICC-header, ICC-meas, ICC-meta, ICC-view, ICC_Profile,
  1477. ICC_Profile#, ID3, ID3v1, ID3v1_Enh, ID3v2_2, ID3v2_3, ID3v2_4, IFD0, IFD1,
  1478. IPTC, IPTC#, ITC, InteropIFD, JFIF, JPEG, JPEG-HDR, JVC, Jpeg2000, KDC_IFD,
  1479. Kodak, KodakBordersIFD, KodakEffectsIFD, KodakIFD, KyoceraRaw, LNK, Leaf,
  1480. LeafSubIFD, Leica, Lytro, M2TS, MAC, MIE-Audio, MIE-Camera, MIE-Canon,
  1481. MIE-Doc, MIE-Extender, MIE-Flash, MIE-GPS, MIE-Geo, MIE-Image, MIE-Lens,
  1482. MIE-Main, MIE-MakerNotes, MIE-Meta, MIE-Orient, MIE-Preview, MIE-Thumbnail,
  1483. MIE-UTM, MIE-Unknown, MIE-Video, MIFF, MNG, MOBI, MOI, MPC, MPEG, MPF0,
  1484. MPImage, MXF, MakerNotes, MakerUnknown, Matroska, MediaJukebox, MetaIFD,
  1485. Microsoft, Minolta, MinoltaRaw, Motorola, NITF, Nikon, NikonCapture,
  1486. NikonCustom, NikonScan, Nintendo, Ocad, Ogg, Olympus, OpenEXR, PDF, PICT,
  1487. PNG, PNG-pHYs, PSP, Palm, Panasonic, PanasonicRaw, Pentax, PhaseOne,
  1488. PhotoCD, PhotoMechanic, Photoshop, PictureInfo, PostScript, PreviewIFD,
  1489. PrintIM, ProfileIFD, Qualcomm, QuickTime, RAF, RAF2, RIFF, RMETA, RSRC, RTF,
  1490. Radiance, Rawzor, Real, Real-CONT, Real-MDPR, Real-PROP, Real-RA3, Real-RA4,
  1491. Real-RA5, Real-RJMD, Reconyx, Ricoh, SPIFF, SR2, SR2DataIFD, SR2SubIFD,
  1492. SRF#, SVG, Samsung, Sanyo, Scalado, Sigma, SigmaRaw, Sony, SonyIDC, Stim,
  1493. SubIFD, System, Theora, Torrent, Track#, VCard, VCalendar, Version0, Vorbis,
  1494. XML, XMP, XMP-DICOM, XMP-GPano, XMP-MP, XMP-MP1, XMP-PixelLive, XMP-aas,
  1495. XMP-acdsee, XMP-album, XMP-apple-fi, XMP-aux, XMP-cc, XMP-cell, XMP-crs,
  1496. XMP-dc, XMP-dex, XMP-digiKam, XMP-dwc, XMP-exif, XMP-exifEX,
  1497. XMP-expressionmedia, XMP-extensis, XMP-fpv, XMP-getty, XMP-ics,
  1498. XMP-iptcCore, XMP-iptcExt, XMP-lr, XMP-mediapro, XMP-microsoft,
  1499. XMP-mwg-coll, XMP-mwg-kw, XMP-mwg-rs, XMP-pdf, XMP-pdfx, XMP-photomech,
  1500. XMP-photoshop, XMP-plus, XMP-prism, XMP-prl, XMP-pur, XMP-rdf, XMP-swf,
  1501. XMP-tiff, XMP-x, XMP-xmp, XMP-xmpBJ, XMP-xmpDM, XMP-xmpMM, XMP-xmpNote,
  1502. XMP-xmpPLUS, XMP-xmpRights, XMP-xmpTPg, ZIP
  1503. =item Family 2 (Category):
  1504. Audio, Author, Camera, Document, ExifTool, Image, Location, Other, Preview,
  1505. Printing, Time, Unknown, Video
  1506. =item Family 3 (Document Number):
  1507. Doc#, Main
  1508. =item Family 4 (Instance Number):
  1509. Copy#
  1510. =back
  1511. =head2 GetDeleteGroups [static]
  1512. Get list of all deletable group names.
  1513. @delGroups = Image::ExifTool::GetDeleteGroups();
  1514. =over 4
  1515. =item Inputs:
  1516. None.
  1517. =item Return Values:
  1518. A list of deletable group names in alphabetical order. The current list of
  1519. deletable group names is:
  1520. AFCP, APP0, APP1, APP10, APP11, APP12, APP13, APP14, APP15, APP2, APP3,
  1521. APP4, APP5, APP6, APP7, APP8, APP9, Adobe, CIFF, CanonVRD, Ducky, EXIF,
  1522. ExifIFD, File, FlashPix, FotoStation, GPS, GlobParamIFD, ICC_Profile, IFD0,
  1523. IFD1, IPTC, InteropIFD, JFIF, Jpeg2000, MIE, MPF, MakerNotes, Meta, MetaIFD,
  1524. NikonCapture, PDF, PDF-update, PNG, PhotoMechanic, Photoshop, PrintIM,
  1525. RMETA, RSRC, SubIFD, Trailer, XML, XML-*, XMP, XMP-*
  1526. All names in this list are either family 0 or family 1 group names, with the
  1527. exception of 'Trailer' which allows all trailers in JPEG and TIFF-format
  1528. images to be deleted at once, including unknown trailers. To schedule a
  1529. group for deletion, call L</SetNewValue> with an undefined value and a tag
  1530. name like 'Trailer:*'.
  1531. Note that the JPEG "APP" groups are special, and are used only to delete
  1532. application segments which are not associated with another deletable group.
  1533. For example, deleting 'APP14:*' will delete other APP14 segments, but not
  1534. the APP14 "Adobe" segment.
  1535. =back
  1536. =head2 GetFileType [static]
  1537. Get type of file given file name.
  1538. my $type = Image::ExifTool::GetFileType($filename);
  1539. my $desc = Image::ExifTool::GetFileType($filename, 1);
  1540. =over 4
  1541. =item Inputs:
  1542. 0) [optional] File name (or just an extension)
  1543. 1) [optional] Flag to return a description instead of a type. Set to 0 to
  1544. return type for recognized but unsupported files (otherwise the return value
  1545. for unsupported files is undef).
  1546. =item Return Value:
  1547. A string, based on the file extension, which indicates the basic format of
  1548. the file. Note that some files may be based on other formats (like many RAW
  1549. image formats are based on TIFF). In array context, may return more than
  1550. one file type if the file may be based on different formats. Returns undef
  1551. if files with this extension are not yet supported by ExifTool. Returns a
  1552. list of extensions for all supported file types if no input extension is
  1553. specified (or all recognized file types if the description flag is set to 0).
  1554. Returns a more detailed description of the specific file format when the
  1555. description flag is set.
  1556. =back
  1557. =head2 CanWrite [static]
  1558. Can the specified file be written?
  1559. my $writable = Image::ExifTool::CanWrite($filename);
  1560. =over 4
  1561. =item Inputs:
  1562. 0) File name or extension
  1563. =item Return Value:
  1564. True if ExifTool supports writing files of this type (based on the file
  1565. extension).
  1566. =back
  1567. =head2 CanCreate [static]
  1568. Can the specified file be created?
  1569. my $creatable = Image::ExifTool::CanCreate($filename);
  1570. =over 4
  1571. =item Inputs:
  1572. 0) File name or extension
  1573. =item Return Value:
  1574. True if ExifTool can create files with this extension from scratch.
  1575. Currently, this can only be done with XMP, MIE, ICC, VRD, DR4, EXV and EXIF
  1576. files.
  1577. =back
  1578. =head2 AddUserDefinedTags [static]
  1579. Add user-defined tags to an existing tag table at run time. This differs
  1580. from the usual technique of creating user-defined tags via the
  1581. %Image::ExifTool::UserDefined hash (see the ExifTool_config file in the
  1582. Image::ExifTool distribution) because it allows tags to be added after the
  1583. tag table has been initialized.
  1584. use Image::ExifTool ':Public';
  1585. my %tags = (
  1586. TestTagID1 => { Name => 'TestTagName1' },
  1587. TestTagID2 => { Name => 'TestTagName2' },
  1588. );
  1589. my $num = AddUserDefinedTags('Image::ExifTool::PDF::Info', %tags);
  1590. =over 4
  1591. =item Inputs:
  1592. 0) Destination tag table name
  1593. 1-N) Pairs of tag ID / tag information hash references for the new tags
  1594. =item Return Value:
  1595. The number of tags added.
  1596. =item Notes
  1597. Pre-existing tags with the same ID will be replaced in the destination
  1598. table. See lib/Image/ExifTool/README in the full distribution for full
  1599. details on the elements of the tag information hash.
  1600. =back
  1601. =head1 CHARACTER ENCODINGS
  1602. Certain meta information formats allow coded character sets other than plain
  1603. ASCII. When reading, most known encodings are converted to the external
  1604. character set according to the L</Charset> option, or to UTF-8 by default.
  1605. When writing, the inverse conversions are performed. Alternatively, special
  1606. characters may be converted to/from HTML character entities with the
  1607. L</Escape> HTML option.
  1608. A distinction is made between the external character set visible via the
  1609. ExifTool API, and the internal character used to store text in the metadata
  1610. of a file. These character sets may be specified separately as follows:
  1611. =over 4
  1612. =item External Character Sets:
  1613. The encoding for tag values passed to/from ExifTool API functions is set via
  1614. the L</Charset> option, which is 'UTF8' by default.
  1615. The encoding of file names is specified via the L</CharsetFileName> option.
  1616. By default, L</CharsetFileName> is not defined, and file names passed to
  1617. ExifTool are used directly in calls to the system i/o routines (which expect
  1618. UTF-8 strings on Mac/Linux, but default to the system code page on Windows).
  1619. Setting L</CharsetFileName> causes file names to be converted from the
  1620. specified encoding to one appropriate for the system. In Windows this also
  1621. has the effect of activating Unicode filename support via the special
  1622. Windows wide-character i/o routines if Win32API::File is available.
  1623. =item Internal Character Sets:
  1624. The encodings used to store strings in the various metadata formats. These
  1625. encodings may be changed for certain types of metadata via the
  1626. L</CharsetEXIF>, L</CharsetID3>, L</CharsetIPTC>, L</CharsetPhotoshop> and
  1627. L</CharsetQuickTime> options.
  1628. =back
  1629. Values are returned as byte strings of encoded characters. Perl wide
  1630. characters are not used. By default, most returned strings are encoded in
  1631. UTF-8. For these, Encode::decode_utf8() may be used to convert to a
  1632. sequence of logical Perl characters. Note that some settings of the
  1633. PERL_UNICODE environment variable may be incompatible with ExifTool's
  1634. character handling.
  1635. More specific details are given below about how character coding is handled
  1636. for EXIF, IPTC, XMP, PNG, ID3, PDF, Photoshop, QuickTime, AIFF, MIE and
  1637. Vorbis information:
  1638. =head2 EXIF
  1639. Most textual information in EXIF is stored in ASCII format (called "string"
  1640. in the L<ExifTool tag name documentation|Image::ExifTool::TagNames>). By
  1641. default ExifTool does not convert these strings. However, it is not
  1642. uncommon for applications to write UTF-8 or other encodings where ASCII is
  1643. expected. To deal with these, ExifTool allows the internal EXIF string
  1644. encoding to be specified with L</CharsetEXIF>, which causes EXIF string
  1645. values to be converted from the specified character set when reading, and
  1646. stored with this character set when writing. (The MWG recommends using
  1647. UTF-8 encoding for EXIF strings, and in keeping with this the
  1648. L<MWG|Image::ExifTool::MWG> module sets the default internal EXIF string
  1649. encoding to UTF-8, but note that this will have no effect unless the
  1650. external encoding is also set to something other than the default of UTF-8.)
  1651. A few EXIF tags (UserComment, GPSProcessingMethod and GPSAreaInformation)
  1652. support a designated internal text encoding, with values stored as ASCII,
  1653. Unicode (UCS-2) or JIS. When reading these tags, ExifTool converts Unicode
  1654. and JIS to the external character set specified by the L</Charset>
  1655. option, or to UTF-8 by default. ASCII text is not converted. When writing,
  1656. text is stored as ASCII unless the string contains special characters, in
  1657. which case it is converted from the external character set (UTF-8 by
  1658. default), and stored as Unicode. ExifTool writes Unicode in native EXIF byte
  1659. ordering by default, but the byte order may be specified by setting the
  1660. ExifUnicodeByteOrder tag (see the
  1661. L<Extra Tags documentation|Image::ExifTool::TagNames/Extra Tags>).
  1662. The EXIF "XP" tags (XPTitle, XPComment, etc) are always stored as
  1663. little-endian Unicode (UCS-2), and are read and written using the specified
  1664. character set.
  1665. =head2 IPTC
  1666. The value of the IPTC:CodedCharacterSet tag determines how the internal IPTC
  1667. string values are interpreted. If CodedCharacterSet exists and has a value
  1668. of 'UTF8' (or 'ESC % G') then string values are assumed to be stored as
  1669. UTF-8, otherwise Windows Latin1 (cp1252, 'Latin') coding is assumed by
  1670. default, but this can be changed with the L</CharsetIPTC> option. When
  1671. reading, these strings are converted to the character set specified by the
  1672. L</Charset> option. When writing, the inverse conversions are performed.
  1673. No conversion is done if the internal (IPTC) and external (ExifTool)
  1674. character sets are the same. Note that ISO 2022 character set shifting is
  1675. not supported. Instead, a warning is issued and the string is not converted
  1676. if an ISO 2022 shift code is encountered. See L<http://www.iptc.org/IIM/>
  1677. for the official IPTC specification.
  1678. ExifTool may be used to convert IPTC values to a different internal
  1679. encoding. To do this, all IPTC tags must be rewritten along with the
  1680. desired value of CodedCharacterSet. For example, the following command
  1681. changes the internal IPTC encoding to UTF-8 (from Windows Latin1 unless
  1682. CodedCharacterSet was already 'UTF8'):
  1683. exiftool -tagsfromfile @ -iptc:all -codedcharacterset=utf8 a.jpg
  1684. or from Windows Latin2 (cp1250) to UTF-8:
  1685. exiftool -tagsfromfile @ -iptc:all -codedcharacterset=utf8 \
  1686. -charset iptc=latin2 a.jpg
  1687. and this command changes it back from UTF-8 to Windows Latin1 (cp1252):
  1688. exiftool -tagsfromfile @ -iptc:all -codedcharacterset= a.jpg
  1689. or to Windows Latin2:
  1690. exiftool -tagsfromfile @ -iptc:all -codedcharacterset= \
  1691. -charset iptc=latin2 a.jpg
  1692. Unless CodedCharacterSet is 'UTF8', applications have no reliable way to
  1693. determine the IPTC character encoding. For this reason, it is recommended
  1694. that CodedCharacterSet be set to 'UTF8' when creating new IPTC.
  1695. (Note: Here, "IPTC" Refers to the older IPTC IIM format. The more recent
  1696. IPTC Core and Extension specifications actually use the XMP format.)
  1697. =head2 XMP
  1698. Exiftool reads XMP encoded as UTF-8, UTF-16 or UTF-32, and converts them all
  1699. to UTF-8 internally. Also, all XML character entity references and numeric
  1700. character references are converted. When writing, ExifTool always encodes
  1701. XMP as UTF-8, converting the following 5 characters to XML character
  1702. references: E<amp> E<lt> E<gt> E<39> E<quot>. By default no further
  1703. conversion is performed, however if the L</Charset> option is other than
  1704. 'UTF8' then text is converted to/from a specified character set when
  1705. reading/writing.
  1706. =head2 PNG
  1707. L<PNG TextualData tags|Image::ExifTool::TagNames/"PNG TextualData Tags"> are
  1708. stored as tEXt, zTXt and iTXt chunks in PNG images. The tEXt and zTXt
  1709. chunks use ISO 8859-1 encoding, while iTXt uses UTF-8. When reading,
  1710. ExifTool converts all PNG textual data to the character set specified by the
  1711. L</Charset> option. When writing, ExifTool generates a tEXt chunk (or zTXt
  1712. with the L</Compress> option) if the text doesn't contain special characters
  1713. or if Latin encoding is specified; otherwise an iTXt chunk is used and the
  1714. text is converted from the specified character set and stored as UTF-8.
  1715. =head2 JPEG Comment
  1716. The encoding for the JPEG Comment (COM segment) is not specified, so
  1717. ExifTool reads/writes this text without conversion.
  1718. =head2 ID3
  1719. The ID3v1 specification officially supports only ISO 8859-1 encoding (a
  1720. subset of Windows Latin1), although some applications may incorrectly use
  1721. other character sets. By default ExifTool converts ID3v1 text from Latin to
  1722. the character set specified by the L</Charset> option. However, the
  1723. internal ID3v1 charset may be specified with the L</CharsetID3> option. The
  1724. encoding for ID3v2 information is stored in the file, so ExifTool converts
  1725. ID3v2 text from this encoding to the character set specified by the
  1726. L</Charset> option. ExifTool does not currently write ID3 information.
  1727. =head2 PDF
  1728. PDF text strings are stored in either PDFDocEncoding (similar to Windows
  1729. Latin1) or Unicode (UCS-2). When reading, ExifTool converts to the
  1730. character set specified by the L</Charset> option. When writing, ExifTool
  1731. encodes input text from the specified character set as Unicode only if the
  1732. string contains special characters, otherwise PDFDocEncoding is used.
  1733. =head2 Photoshop
  1734. Some Photoshop resource names are stored as Pascal strings with unknown
  1735. encoding. By default, ExifTool assumes MacRoman encoding and converts this
  1736. to UTF-8, but the internal and external character sets may be specified with
  1737. L</CharsetPhotoshop> and L</Charset> options respectively.
  1738. =head2 QuickTime
  1739. QuickTime text strings may be stored in a variety of poorly document
  1740. formats. ExifTool does its best to decode these according to the L</Charset>
  1741. option setting. For some QuickTime strings, ExifTool assumes a default
  1742. encoding of MacRoman, but this may be changed with the L</CharsetQuickTime>
  1743. option.
  1744. =head2 AIFF
  1745. AIFF strings are assumed to be stored in MacRoman, and are converted
  1746. according to the L</Charset> option when reading.
  1747. =head2 MIE
  1748. MIE strings are stored as either UTF-8 or ISO 8859-1. When reading, UTF-8
  1749. strings are converted according to the L</Charset> option, and ISO 8859-1
  1750. strings are never converted. When writing, input strings are converted from
  1751. the specified character set to UTF-8. The resulting strings are stored as
  1752. UTF-8 if they contain multi-byte UTF-8 character sequences, otherwise they
  1753. are stored as ISO 8859-1.
  1754. =head2 Vorbis
  1755. Vorbis comments are stored as UTF-8, and are converted to the character set
  1756. specified by the L</Charset> option.
  1757. =head1 AUTHOR
  1758. Copyright 2003-2016, Phil Harvey
  1759. This library is free software; you can redistribute it and/or modify it
  1760. under the same terms as Perl itself.
  1761. =head1 ACKNOWLEDGEMENTS
  1762. Many people have helped in the development of ExifTool through their bug
  1763. reports, comments and suggestions, and/or additions to the code. See the
  1764. ACKNOWLEDGEMENTS in the individual Image::ExifTool modules and in
  1765. html/index.html of the Image::ExifTool distribution package for a list of
  1766. people who have contributed to this project.
  1767. =head1 SEE ALSO
  1768. L<exiftool(1)|exiftool>,
  1769. L<Image::ExifTool::TagNames(3pm)|Image::ExifTool::TagNames>,
  1770. L<Image::ExifTool::Shortcuts(3pm)|Image::ExifTool::Shortcuts>,
  1771. L<Image::ExifTool::Shift.pl|Image::ExifTool::Shift.pl>,
  1772. L<Image::Info(3pm)|Image::Info>,
  1773. L<Image::MetaData::JPEG(3pm)|Image::MetaData::JPEG>
  1774. =cut
  1775. # end