12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382138313841385138613871388138913901391139213931394139513961397139813991400140114021403140414051406140714081409141014111412141314141415141614171418141914201421142214231424142514261427142814291430143114321433143414351436143714381439144014411442144314441445144614471448144914501451145214531454145514561457145814591460146114621463146414651466146714681469147014711472147314741475147614771478147914801481148214831484148514861487148814891490149114921493149414951496149714981499150015011502150315041505150615071508150915101511151215131514151515161517151815191520152115221523152415251526152715281529153015311532153315341535153615371538153915401541154215431544154515461547154815491550155115521553155415551556155715581559156015611562156315641565156615671568156915701571157215731574157515761577157815791580158115821583158415851586158715881589159015911592159315941595159615971598159916001601160216031604160516061607160816091610161116121613161416151616161716181619162016211622162316241625162616271628162916301631163216331634163516361637163816391640164116421643164416451646164716481649165016511652165316541655165616571658165916601661166216631664166516661667166816691670167116721673167416751676167716781679168016811682168316841685168616871688168916901691169216931694169516961697169816991700170117021703170417051706170717081709171017111712171317141715171617171718171917201721172217231724172517261727172817291730173117321733173417351736173717381739174017411742174317441745174617471748174917501751175217531754175517561757175817591760176117621763176417651766176717681769177017711772177317741775177617771778177917801781178217831784178517861787178817891790179117921793179417951796179717981799180018011802180318041805180618071808180918101811181218131814181518161817181818191820182118221823182418251826182718281829183018311832183318341835183618371838183918401841184218431844184518461847184818491850185118521853185418551856185718581859186018611862186318641865186618671868186918701871187218731874187518761877187818791880188118821883188418851886188718881889189018911892189318941895189618971898189919001901190219031904190519061907190819091910191119121913191419151916191719181919192019211922192319241925192619271928192919301931193219331934193519361937193819391940194119421943194419451946194719481949195019511952195319541955195619571958195919601961196219631964196519661967196819691970197119721973197419751976197719781979198019811982198319841985198619871988198919901991199219931994199519961997199819992000200120022003200420052006200720082009201020112012201320142015201620172018201920202021202220232024202520262027202820292030203120322033203420352036203720382039204020412042204320442045204620472048204920502051205220532054205520562057205820592060206120622063206420652066206720682069207020712072207320742075207620772078207920802081208220832084208520862087208820892090209120922093209420952096209720982099210021012102210321042105210621072108210921102111211221132114211521162117211821192120212121222123212421252126212721282129213021312132213321342135213621372138213921402141214221432144214521462147214821492150215121522153215421552156215721582159216021612162216321642165216621672168216921702171217221732174217521762177217821792180218121822183218421852186218721882189219021912192219321942195219621972198219922002201220222032204220522062207220822092210221122122213221422152216221722182219222022212222222322242225222622272228222922302231223222332234223522362237223822392240224122422243224422452246224722482249225022512252225322542255225622572258225922602261226222632264226522662267226822692270227122722273227422752276227722782279228022812282228322842285228622872288228922902291229222932294229522962297229822992300230123022303230423052306230723082309231023112312231323142315231623172318231923202321232223232324232523262327232823292330233123322333233423352336233723382339234023412342234323442345234623472348234923502351235223532354235523562357235823592360236123622363236423652366236723682369237023712372237323742375237623772378237923802381238223832384238523862387238823892390239123922393239423952396239723982399240024012402240324042405240624072408240924102411241224132414241524162417241824192420242124222423242424252426242724282429243024312432243324342435243624372438243924402441244224432444244524462447244824492450245124522453245424552456245724582459246024612462246324642465246624672468246924702471247224732474247524762477247824792480248124822483248424852486248724882489249024912492249324942495249624972498249925002501250225032504250525062507250825092510251125122513251425152516251725182519252025212522252325242525252625272528 |
- #------------------------------------------------------------------------------
- # File: ExifTool.pod - Documentation for File::ExifTool
- #
- # Description: Read and write meta information
- #
- # URL: http://owl.phy.queensu.ca/~phil/exiftool/
- #
- # Legal: Copyright (c) 2003-2016, Phil Harvey (phil at owl.phy.queensu.ca)
- # This library is free software; you can redistribute it and/or
- # modify it under the same terms as Perl itself.
- #------------------------------------------------------------------------------
- =head1 NAME
- Image::ExifTool - Read and write meta information
- =head1 SYNOPSIS
- use Image::ExifTool qw(:Public);
- # ---- Simple procedural usage ----
- # Get hash of meta information tag names/values from an image
- $info = ImageInfo('a.jpg');
- # ---- Object-oriented usage ----
- # Create a new Image::ExifTool object
- $exifTool = new Image::ExifTool;
- # Extract meta information from an image
- $exifTool->ExtractInfo($file, \%options);
- # Get list of tags in the order they were found in the file
- @tagList = $exifTool->GetFoundTags('File');
- # Get the value of a specified tag
- $value = $exifTool->GetValue($tag, $type);
- # Get a tag description
- $description = $exifTool->GetDescription($tag);
- # Get the group name associated with this tag
- $group = $exifTool->GetGroup($tag, $family);
- # Set a new value for a tag
- $exifTool->SetNewValue($tag, $newValue);
- # Write new meta information to a file
- $success = $exifTool->WriteInfo($srcfile, $dstfile);
- # ...plus a host of other useful methods...
- =head1 DESCRIPTION
- Reads and writes meta information in a wide variety of files, including the
- maker notes of many digital cameras by various manufacturers such as Canon,
- Casio, FLIR, FujiFilm, GE, HP, JVC/Victor, Kodak, Leaf,
- Minolta/Konica-Minolta, Nikon, Nintendo, Olympus/Epson, Panasonic/Leica,
- Pentax/Asahi, Phase One, Reconyx, Ricoh, Samsung, Sanyo, Sigma/Foveon and
- Sony.
- Below is a list of file types and meta information formats currently
- supported by ExifTool (r = read, w = write, c = create):
- File Types
- ------------+-------------+-------------+-------------+------------
- 3FR r | DVB r/w | KEY r | ORF r/w | RWL r/w
- 3G2 r/w | DYLIB r | LA r | OTF r | RWZ r
- 3GP r/w | EIP r | LFP r | PAC r | RM r
- AA r | EPS r/w | LNK r | PAGES r | SEQ r
- AAX r/w | EPUB r | M2TS r | PBM r/w | SO r
- ACR r | ERF r/w | M4A/V r/w | PCD r | SR2 r/w
- AFM r | EXE r | MEF r/w | PDB r | SRF r
- AI r/w | EXIF r/w/c | MIE r/w/c | PDF r/w | SRW r/w
- AIFF r | EXR r | MIFF r | PEF r/w | SVG r
- APE r | EXV r/w/c | MKA r | PFA r | SWF r
- ARW r/w | F4A/V r/w | MKS r | PFB r | THM r/w
- ASF r | FFF r/w | MKV r | PFM r | TIFF r/w
- AVI r | FLA r | MNG r/w | PGF r | TORRENT r
- AZW r | FLAC r | MOBI r | PGM r/w | TTC r
- BMP r | FLV r | MODD r | PLIST r | TTF r
- BTF r | FPF r | MOI r | PICT r | VCF r
- CHM r | FPX r | MOS r/w | PMP r | VRD r/w/c
- COS r | GIF r/w | MOV r/w | PNG r/w | VSD r
- CR2 r/w | GZ r | MP3 r | PPM r/w | WAV r
- CRW r/w | HDP r/w | MP4 r/w | PPT r | WDP r/w
- CS1 r/w | HDR r | MPC r | PPTX r | WEBP r
- DCM r | HTML r | MPG r | PS r/w | WEBM r
- DCP r/w | ICC r/w/c | MPO r/w | PSB r/w | WMA r
- DCR r | ICS r | MQV r/w | PSD r/w | WMV r
- DFONT r | IDML r | MRW r/w | PSP r | WV r
- DIVX r | IIQ r/w | MXF r | QTIF r/w | X3F r/w
- DJVU r | IND r/w | NEF r/w | RA r | XCF r
- DLL r | INX r | NRW r/w | RAF r/w | XLS r
- DNG r/w | ITC r | NUMBERS r | RAM r | XLSX r
- DOC r | J2C r | ODP r | RAR r | XMP r/w/c
- DOCX r | JNG r/w | ODS r | RAW r/w | ZIP r
- DPX r | JP2 r/w | ODT r | RIFF r |
- DR4 r/w/c | JPEG r/w | OFR r | RSRC r |
- DSS r | K25 r | OGG r | RTF r |
- DV r | KDC r | OGV r | RW2 r/w |
- Meta Information
- ----------------------+----------------------+---------------------
- EXIF r/w/c | CIFF r/w | Ricoh RMETA r
- GPS r/w/c | AFCP r/w | Picture Info r
- IPTC r/w/c | Kodak Meta r/w | Adobe APP14 r
- XMP r/w/c | FotoStation r/w | MPF r
- MakerNotes r/w/c | PhotoMechanic r/w | Stim r
- Photoshop IRB r/w/c | JPEG 2000 r | DPX r
- ICC Profile r/w/c | DICOM r | APE r
- MIE r/w/c | Flash r | Vorbis r
- JFIF r/w/c | FlashPix r | SPIFF r
- Ducky APP12 r/w/c | QuickTime r | DjVu r
- PDF r/w/c | Matroska r | M2TS r
- PNG r/w/c | MXF r | PE/COFF r
- Canon VRD r/w/c | PrintIM r | AVCHD r
- Nikon Capture r/w/c | FLAC r | ZIP r
- GeoTIFF r/w/c | ID3 r | (and more)
- =head1 CONFIGURATION
- User-defined tags can be added via the ExifTool configuration file, or by
- defining the %Image::ExifTool::UserDefined hash before calling any ExifTool
- methods. See "ExifTool_config" in the ExifTool distribution for more
- details.
- By default ExifTool looks for a configuration file named ".ExifTool_config"
- first in your home directory, then in the directory of the application
- script, but a different directory may be specified by setting the
- EXIFTOOL_HOME environment variable, or a different file may be specified by
- setting the ExifTool C<configFile> variable before using Image::ExifTool.
- For example:
- BEGIN { $Image::ExifTool::configFile = '/Users/phil/myconfig.cfg' }
- use Image::ExifTool;
- The configuration feature may also be disabled by setting C<configFile> to
- an empty string:
- BEGIN { $Image::ExifTool::configFile = '' }
- use Image::ExifTool;
- =head1 EXPORTS
- Exports nothing by default, but L</ImageInfo> and all static methods may be
- exported with the C<:Public> export list.
- =head1 METHODS
- All ExifTool features are accessed through the methods of the public
- interface listed below. Other Image::ExifTool methods and modules should
- not be accessed directly because their interface may change with future
- versions.
- None of these methods should ever die or issue warnings to STDERR if called
- with the proper arguments (with the exception of L</SetNewValue> which may
- send an error message to STDERR, but only when called in scalar context).
- Error and warning messages that occur during processing are stored in the
- values of the Error and Warning tags, and are accessible via the
- L</GetValue> method to retrieve a single Error or Warning message, or
- L</GetInfo> to retrieve any number of them.
- The ExifTool methods are not thread safe.
- =head2 new
- Creates a new ExifTool object.
- $exifTool = new Image::ExifTool;
- Note that ExifTool uses AUTOLOAD to load non-member methods, so any class
- using Image::ExifTool as a base class must define an AUTOLOAD which calls
- Image::ExifTool::DoAutoLoad(). eg)
- sub AUTOLOAD
- {
- Image::ExifTool::DoAutoLoad($AUTOLOAD, @_);
- }
- =head2 ImageInfo
- Read image file and return meta information. This is the one step function
- for retrieving meta information from an image. Internally, L</ImageInfo>
- calls L</ExtractInfo> to extract the information, L</GetInfo> to generate
- the information hash, and L</GetTagList> for the returned tag list.
- # return meta information for 2 tags only (procedural)
- $info = ImageInfo($filename, $tag1, $tag2);
- # return information about an open image file (object-oriented)
- $info = $exifTool->ImageInfo(\*FILE);
- # return information from image data in memory for specified tags
- %options = (PrintConv => 0);
- @tagList = qw(filename imagesize xmp:creator exif:* -ifd1:*);
- $info = ImageInfo(\$imageData, \@tagList, \%options);
- # extract information from an embedded thumbnail image
- $info = ImageInfo('image.jpg', 'thumbnailimage');
- $thumbInfo = ImageInfo($$info{ThumbnailImage});
- =over 4
- =item Inputs:
- L</ImageInfo> is very flexible about the input arguments, and interprets
- them based on their type. It may be called with one or more arguments.
- The one required argument is either a SCALAR (the image file name), a file
- reference (a reference to the image file) or a SCALAR reference (a
- reference to the image in memory). Other arguments are optional. The
- order of the arguments is not significant, except that the first SCALAR is
- taken to be the file name unless a file reference or scalar reference comes
- earlier in the argument list.
- Below is an explanation of how the L</ImageInfo> function arguments are
- interpreted:
- =over 4
- =item ExifTool ref
- L</ImageInfo> may be called with an ExifTool object if desired. Advantages
- of using the object-oriented form are that options may be set before calling
- L</ImageInfo>, and the object may be used afterward to access member
- functions. Must be the first argument if used.
- =item SCALAR
- The first scalar argument is taken to be the file name unless an earlier
- argument specified the image data via a file reference (file ref) or data
- reference (SCALAR ref). The remaining scalar arguments are names of tags
- for requested information. All tags are returned if no tags are specified.
- Tag names are case-insensitive and may be prefixed by optional group names
- separated by colons. A group name may begin with a family number (eg.
- '1IPTC:Keywords'), to restrict matches to a specific family. In the tag
- name, a '?' matches any single character and a '*' matches zero or more
- characters. Thus 'GROUP:*' represents all tags in a specific group.
- Wildcards may not be used in group names, with the exception that a group
- name of '*' may be used to extract all available instances of a tag
- regardless of the L</Duplicates> setting (eg. '*:WhiteBalance'). Multiple
- groups may be specified (eg. 'EXIF:Time:*' extracts all EXIF Time tags). And
- finally, a leading '-' indicates a tag to be excluded (eg. '-IFD1:*'), or a
- trailing '#' causes the ValueConv value to be returned for this tag.
- Note that keys in the returned information hash and elements of the returned
- tag list are not necessarily the same as these tag names because group names
- are removed, the case may be changed, and an instance number may be added.
- For this reason it is best to use either the keys of the returned hash or
- the elements of the returned tag list when accessing the tag values.
- See L<Image::ExifTool::TagNames|Image::ExifTool::TagNames> for a complete
- list of ExifTool tag names.
- =item File ref
- A reference to an open image file. If you use this method (or a SCALAR
- reference) to access information in an image, the FileName and Directory
- tags will not be returned. (Also, a number of the File System tags will not
- be returned unless it is a plain file.) Image processing begins at the
- current file position, and on return the file position is unspecified. May
- be either a standard filehandle, or a reference to a
- L<File::RandomAccess|File::RandomAccess> object. Note that the file remains
- open and must be closed by the caller after L</ImageInfo> returns.
- [Advanced: To allow a non-rewindable stream (eg. a network socket) to be
- re-read after processing with ExifTool, first wrap the file reference in a
- L<File::RandomAccess|File::RandomAccess> object, then pass this object to
- L</ImageInfo>. The L<File::RandomAccess|File::RandomAccess> object will
- buffer the file if necessary, and may be used to re-read the file after
- L</ImageInfo> returns.]
- =item SCALAR ref
- A reference to image data in memory.
- =item ARRAY ref
- Reference to a list of tag names. On entry, any elements in the list are
- added to the list of requested tags. Tags with names beginning with '-' are
- excluded. On return, this list is updated to contain an ordered list of tag
- keys for the returned information.
- There will be 1:1 correspondence between the requested tags and the returned
- tag keys only if the L</Duplicates> option is 0 and L</Sort> is 'Input'.
- (With L</Duplicates> enabled, there may be more entries in the returned list
- of tag keys, and with other L</Sort> settings the entries may not be in the
- same order as requested.) If a requested tag doesn't exist, a tag key is
- still generated, but the tag value is undefined.
- =item HASH ref
- Reference to a hash containing the options settings. See L</Options>
- documentation below for a list of available options. Options specified
- as arguments to L</ImageInfo> take precedence over L</Options> settings.
- =back
- =item Return Values:
- L</ImageInfo> returns a reference to a hash of tag key/value pairs. The tag
- keys are identifiers, which are similar to the tag names but may have an
- appended instance number if multiple tags with the same name were extracted
- from the image. Many of the ExifTool functions require a tag key as an
- argument. Use L</GetTagName [static]> to get the tag name for a given tag
- key. Note that the case of the tag names may not be the same as requested.
- Here is a simple example to print out the information returned by
- L</ImageInfo>:
- foreach (sort keys %$info) {
- print "$_ => $$info{$_}\n";
- }
- Values of the returned hash are usually simple scalars, but a scalar
- reference is used to indicate binary data and an array reference may be used
- to indicate a list. Also, a hash reference may be returned if the L</Struct>
- option is used. Lists of values are joined by commas into a single
- string only if the PrintConv option is enabled and the List option is
- disabled (which are the defaults). Note that binary values are not
- necessarily extracted unless specifically requested, or the Binary option is
- enabled and the tag is not specifically excluded. If not extracted the
- value is a reference to a string of the form "Binary data ##### bytes".
- The code below gives an example of how to handle these return values, as
- well as illustrating the use of other ExifTool functions:
- use Image::ExifTool;
- my $exifTool = new Image::ExifTool;
- $exifTool->Options(Unknown => 1);
- my $info = $exifTool->ImageInfo('a.jpg');
- my $group = '';
- my $tag;
- foreach $tag ($exifTool->GetFoundTags('Group0')) {
- if ($group ne $exifTool->GetGroup($tag)) {
- $group = $exifTool->GetGroup($tag);
- print "---- $group ----\n";
- }
- my $val = $info->{$tag};
- if (ref $val eq 'SCALAR') {
- if ($$val =~ /^Binary data/) {
- $val = "($$val)";
- } else {
- my $len = length($$val);
- $val = "(Binary data $len bytes)";
- }
- }
- printf("%-32s : %s\n", $exifTool->GetDescription($tag), $val);
- }
- =item Notes:
- ExifTool returns all values as byte strings of encoded characters. Perl
- wide characters are not used. See L</CHARACTER ENCODINGS> for details about
- the encodings. By default, most returned values are encoded in UTF-8. For
- these, Encode::decode_utf8() may be used to convert to a sequence of logical
- Perl characters.
- As well as tags representing information extracted from the image, the
- following L<Extra tags|Image::ExifTool::TagNames/Extra Tags> generated by
- ExifTool may be returned:
- ExifToolVersion - The ExifTool version number.
- Error - An error message if the image could not be processed.
- Warning - A warning message if problems were encountered while
- processing the image.
- =back
- =head2 Options
- Get/set ExifTool options. This function can be called to set the default
- options for an ExifTool object. Options set this way are in effect for
- all function calls but may be overridden by options passed as arguments
- to some functions. Option names are not case sensitive.
- The default option values may be changed by defining a
- %Image::ExifTool::UserDefined::Options hash. See the ExifTool_config file
- in the full ExifTool distribution for examples.
- # exclude the 'OwnerName' tag from returned information
- $exifTool->Options(Exclude => 'OwnerName');
- # only get information in EXIF or MakerNotes groups
- $exifTool->Options(Group0 => ['EXIF', 'MakerNotes']);
- # ignore information from IFD1
- $exifTool->Options(Group1 => '-IFD1');
- # sort by groups in family 2, and extract unknown tags
- $exifTool->Options(Sort => 'Group2', Unknown => 1);
- # reset DateFormat option
- $exifTool->Options(DateFormat => undef);
- # do not extract duplicate tag names
- $oldSetting = $exifTool->Options(Duplicates => 0);
- # get current Verbose setting
- $isVerbose = $exifTool->Options('Verbose');
- # set a user parameter
- $exifTool->Options(UserParam => 'MyParam=some value');
- =over 4
- =item Inputs:
- 0) ExifTool object reference
- 1) Option parameter name (case-insensitive)
- 2) [optional] Option parameter value (may be undef to clear option)
- 3-N) [optional] Additional parameter/value pairs
- =item Option Parameters:
- =over 4
- =item Binary
- Flag to extract the value data for all binary tags. Tag values representing
- large binary data blocks (eg. ThumbnailImage) are not necessarily extracted
- unless this option is set or the tag is specifically requested by name.
- Default is undef.
- =item ByteOrder
- The byte order for newly created EXIF segments when writing. Note that if
- EXIF information already exists, the existing order is maintained. Valid
- values are 'MM', 'II' and undef. If ByteOrder is not defined (the default),
- then the maker note byte order is used (if they are being copied), otherwise
- big-endian ('MM') order is assumed. This can also be set via the
- L<ExifByteOrder tag|Image::ExifTool::TagNames/Extra Tags>, but the ByteOrder
- option takes precedence if both are set.
- =item Charset
- Character set for encoding character tag values passed to/from ExifTool with
- code points above U+007F. Default is 'UTF8'. Valid values are listed
- below, case is not significant:
- Value Alias(es) Description
- ----------- --------------- ----------------------------------
- UTF8 cp65001, UTF-8 UTF-8 characters
- Latin cp1252, Latin1 Windows Latin1 (West European)
- Latin2 cp1250 Windows Latin2 (Central European)
- Cyrillic cp1251, Russian Windows Cyrillic
- Greek cp1253 Windows Greek
- Turkish cp1254 Windows Turkish
- Hebrew cp1255 Windows Hebrew
- Arabic cp1256 Windows Arabic
- Baltic cp1257 Windows Baltic
- Vietnam cp1258 Windows Vietnamese
- Thai cp874 Windows Thai
- MacRoman cp10000, Roman Macintosh Roman
- MacLatin2 cp10029 Macintosh Latin2 (Central Europe)
- MacCyrillic cp10007 Macintosh Cyrillic
- MacGreek cp10006 Macintosh Greek
- MacTurkish cp10081 Macintosh Turkish
- MacRomanian cp10010 Macintosh Romanian
- MacIceland cp10079 Macintosh Icelandic
- MacCroatian cp10082 Macintosh Croatian
- Note that this option affects some types of information when reading/writing
- the file and other types when getting/setting tag values, so it must be
- defined for both types of access. See the L</CHARACTER ENCODINGS> section
- for more information about the handling of special characters.
- =item CharsetEXIF
- Internal encoding to use for stored EXIF "ASCII" string values. May also be
- set to undef to pass through EXIF "ASCII" values without recoding. Set to
- "UTF8" to conform with the MWG recommendation. Default is undef.
- =item CharsetFileName
- External character set used for file names passed to ExifTool functions.
- When set in Windows, this triggers use of Windows wide-character i/o library
- routines (requires Win32API::File). Default is undef.
- =item CharsetID3
- Internal encoding to assume for ID3v1 strings. By the specification ID3v1
- strings should be encoded in ISO 8859-1 (essentially Latin), but some
- applications may use local encoding instead. Default is 'Latin'.
- =item CharsetIPTC
- Fallback internal IPTC character set to assume if IPTC information contains
- no CodedCharacterSet tag. Possible values are the same as the L</Charset>
- option. Default is 'Latin'.
- Note that this option affects some types of information when reading/writing
- the file and other types when getting/setting tag values, so it must be
- defined for both types of access.
- =item CharsetPhotoshop
- Internal encoding to assume for Photoshop IRB resource names. Default is
- 'Latin'.
- =item CharsetQuickTime
- Internal encoding to assume for QuickTime strings stored with an unspecified
- encoding. Default is 'MacRoman'.
- =item Compact
- Flag to write compact output. Default is undef. The XMP specification
- suggests that the data be padded with blanks to allow in-place editing.
- With this flag set the 2kB of padding is not written. Note that this only
- effects embedded XMP since padding is never written for stand-alone XMP
- files.
- =item Composite
- Flag to generate Composite tags when extracting information. Default is 1.
- =item Compress
- Flag to write new values in compressed format if possible. Has no effect
- unless Compress::Zlib is installed. Default is undef.
- =item CoordFormat
- Format for printing GPS coordinates. This is a printf format string with
- specifiers for degrees, minutes and seconds in that order, however minutes
- and seconds may be omitted. If the hemisphere is known, a reference
- direction (N, S, E or W) is appended to each printed coordinate, but adding
- a C<+> to the first format specifier (eg. C<%+.6f>) prints a signed
- coordinate instead. For example, the following table gives the output for
- the same coordinate using various formats:
- CoordFormat Example Output
- ------------------- ------------------
- q{%d deg %d' %.2f"} 54 deg 59' 22.80" (default for reading)
- q{%d %d %.8f} 54 59 22.80000000 (default for copying)
- q{%d deg %.4f min} 54 deg 59.3800 min
- q{%.6f degrees} 54.989667 degrees
- Note: To avoid loss of precision, the default coordinate format is
- different when copying tags with L</SetNewValuesFromFile>.
- =item DateFormat
- Format for printing date/time values. See C<strftime> in the L<POSIX>
- package for details about the format string. The default is similar to a
- format of "%Y:%m:%d %H:%M:%S". If date can not be converted, value is left
- unchanged unless the StrictDate option is set. Timezones are ignored.
- =item Duplicates
- Flag to return values from tags with duplicate names when extracting
- information. Default is 1.
- =item Escape
- Escape special characters in extracted values for HTML or XML. Also
- unescapes HTML or XML character entities in input values passed to
- L</SetNewValue>. Valid settings are 'HTML', 'XML' or undef. Default is
- undef.
- =item Exclude
- Exclude specified tags from tags extracted from an image. The option value
- is either a tag name or reference to a list of tag names to exclude. The
- case of tag names is not significant. This option is ignored for
- specifically requested tags. Tags may also be excluded by preceding their
- name with a '-' in the arguments to L</ImageInfo>.
- =item ExtendedXMP
- This setting affects the reading and editing of extended XMP in JPEG images.
- According to the XMP specification, extended XMP is only valid if it has the
- GUID specified by the HasExtendedXMP tag. ExifTool 9.95 and earlier would
- read extended XMP regardless of GUID, but with the addition of this option
- in version 9.96 the default behaviour was changed to conform with the XMP
- specification (to read only extended XMP with the proper GUID). This option
- should be set to 2 to emulate pre-9.96 behaviour and read all extended XMP.
- It may also be set to a GUID to read a specific extended XMP, or 0 to ignore
- extended XMP entirely.
- 0 - ignore all extended XMP
- 1 - read extended XMP with valid GUID only (default)
- 2 - read extended XMP with any GUID
- <guid> - read extended XMP with a specific GUID
- =item ExtractEmbedded
- Flag to extract information from embedded documents in EPS files, embedded
- EPS information and JPEG and Jpeg2000 images in PDF files, embedded MPF
- images in JPEG and MPO files, streaming metadata in AVCHD videos, and the
- resource fork of Mac OS files. Default is undef.
- =item FastScan
- Flag to increase speed of extracting information from JPEG images. With
- this option set to 1, ExifTool will not scan to the end of a JPEG image to
- check for an AFCP, CanonVRD, FotoStation, PhotoMechanic, MIE or PreviewImage
- trailer. This also stops the parsing after the first comment in GIF images,
- and at the audio/video data with RIFF-format files (AVI, WAV, etc), so any
- trailing metadata (eg. XMP written by some utilities) may be missed. When
- combined with the ScanForXMP option, prevents scanning for XMP in recognized
- file types. With a value of 2, ExifTool will also avoid extracting any EXIF
- MakerNote information. When set to 3, the file is not actually parsed, and
- only an initial guess at FileType and some pseudo tags are returned.
- Default is undef.
- =item Filter
- Perl expression used to filter values for all tags. The expression acts on
- the value of the Perl default variable ($_), and changes the value of this
- variable as required. Applies to all returned values unless PrintConv
- option is disabled.
- =item FixBase
- Fix maker notes base offset. A common problem with image editing software
- is that offsets in the maker notes are not adjusted properly when the file
- is modified. This may cause the wrong values to be extracted for some maker
- note entries when reading the edited file. FixBase specifies an integer
- value to be added to the maker notes base offset. It may also be set to the
- empty string ('') for ExifTool will take its best guess at the correct base,
- or undef (the default) for no base adjustment.
- =item GeoMaxIntSecs
- Maximum interpolation time in seconds for geotagging. Geotagging is treated
- as an extrapolation if the Geotime value lies between two fixes in the same
- track which are separated by a number of seconds greater than this.
- Otherwise, the coordinates are calculated as a linear interpolation between
- the nearest fixes on either side of the Geotime value. Set to 0 to disable
- interpolation and use the coordinates of the nearest fix instead (provided
- it is within GeoMaxExtSecs, otherwise geotagging fails). Default is 1800.
- =item GeoMaxExtSecs
- Maximum extrapolation time in seconds for geotagging. Geotagging fails if
- the Geotime value lies outside a GPS track by a number of seconds greater
- than this. Otherwise, the coordinates of the nearest fix are taken.
- Default is 1800.
- =item GeoMaxHDOP
- Maximum Horizontal (2D) Dilution Of Precision for geotagging. GPS fixes are
- ignored if the HDOP is greater than this. Default is undef.
- =item GeoMaxPDOP
- Maximum Position (3D) Dilution Of Precision for geotagging. GPS fixes are
- ignored if the PDOP is greater than this. Default is undef.
- =item GeoMinSats
- Minimum number of satellites for geotagging. GPS fixes are ignored if the
- number of acquired satellites is less than this. Default is undef.
- =item GlobalTimeShift
- Time shift to apply to all extracted date/time PrintConv values. Does not
- affect ValueConv values. Value is a date/time shift string (see
- L<Image::ExifTool::Shift.pl|Image::ExifTool::Shift.pl>), with a leading '-'
- for negative shifts. Default is undef.
- =item Group#
- Extract tags only for specified groups in family # (Group0 assumed if #
- not given). The option value may be a single group name or a reference
- to a list of groups. Case is significant in group names. Specify a group
- to be excluded by preceding group name with a '-'. See L</GetGroup> for a
- description of group families, and L</GetAllGroups [static]> for lists of
- group names.
- =item HtmlDump
- Dump information in hex to dynamic HTML web page. The value may be 0-3 for
- increasingly larger limits on the maximum block size. Default is 0. Output
- goes to the file specified by the TextOut option (\*STDOUT by default).
- =item HtmlDumpBase
- Base for HTML dump offsets. If not defined, the EXIF/TIFF base offset is
- used. Set to 0 for absolute offsets. Default is undef.
- =item IgnoreMinorErrors
- Flag to ignore minor errors. Causes minor errors to be downgraded to
- warnings, and minor warnings to be ignored. This option is provided mainly
- to allow writing of files when minor errors occur, but by ignoring some
- minor warnings the behaviour of ExifTool may be changed to allow some
- questionable operations to proceed (such as extracting thumbnail and preview
- images even if they don't have a recognizable header). Minor errors and
- warnings are denoted by "[minor]" at the start of the message, or "[Minor]"
- (with a capital "M") for warnings that affect processing when ignored.
- =item Lang
- Localized language for exiftool tag descriptions, etc. Available languages
- are given by the Image::ExifTool::Lang module names (eg. 'fr', 'zh_cn'). If
- the specified language isn't available, the option is not changed. May be
- set to undef to select the built-in default language. Default is 'en'.
- =item LargeFileSupport
- Flag to indicate that 64-bit file offsets are supported on this system.
- Default is undef.
- =item List
- Flag to extract lists of PrintConv values into arrays instead of joining
- them into a string of values. The L</ListSep> option specifies the
- separator used when combining values. Default is undef.
- =item ListItem
- Return only a specific item from List-type values. A value of 0 returns the
- first item in the list, 1 return the second item, etc. Negative indices may
- also be used, with -1 representing the last item in the list. Applies only
- to the top-level list of nested lists. Default is undef to return all items
- in the list.
- =item ListSep
- Separator string used to join lists of PrintConv values when L</List> option
- is not set. Default is ', '.
- =item ListSplit
- Regular expression used to split values of list-type tags into individual
- items when writing. (eg. use ',\\s*' to split a comma-separated list.)
- Default is undef.
- =item MakerNotes
- Option to extract MakerNotes and other writable subdirectories (such as
- PrintIM) as a data block. Normally when the MakerNotes are extracted they
- are rebuilt to include data outside the boundaries of the original maker
- note data block, but a value of 2 disables this feature. Possible values
- are:
- 0 - Do not extract writable subdirectories (same as default of undef)
- 1 - Extract and rebuild maker notes into self-contained block
- 2 - Extract without rebuilding maker notes
- =item MDItemTags
- Flag to extract the OS X metadata item tags (see the "mdls" man page for
- details).
- =item MissingTagValue
- Value for missing tags in expressions evaluated by L</SetNewValuesFromFile>.
- If not set, a minor error is issued for missing values, or the value is set
- to '' if L</IgnoreMinorErrors> is set. Default is undef.
- =item NoPDFList
- Flag to avoid splitting PDF List-type tag values into separate items.
- Default is undef.
- =item Password
- Password for reading/writing password-protected PDF documents. Ignored if a
- password is not required. Character encoding of the password is determined
- by the value of the Charset option at processing time. Default is undef.
- =item PNGEarlyXMP
- Flag to write XMP in PNG images before the IDAT (image data) chunk. By
- default, ExifTool adds new XMP to the end of a PNG file (just before IEND).
- This is allowed by the PNG and XMP specifications, but some utilities seem
- to ignore XMP if it comes after the image data. The PNGEarlyXMP option
- causes ExifTool to instead add new XMP before the PNG IDAT chunk. However,
- since ExifTool uses a single-pass writing algorithm, it has no way to tell
- if XMP already exists later in the file before writing the new XMP in this
- location. If this happens, a minor error is issued when the extra XMP is
- encountered, and the file is not written. Adding the L</IgnoreMinorErrors>
- option causes the XMP after IDAT to be deleted, thus resolving the conflict
- (at the expense of possible metadata loss), and allowing the file to be
- written. The PNGEarlyXMP option is applied automatically when deleting all
- XMP and writing new XMP back in one step. When reading, this option causes
- a warning to be issued if standard XMP is found after the IDAT chunk.
- =item PrintConv
- Flag to enable automatic print conversion. Also enables inverse
- print conversion for writing. Default is 1.
- =item QuickTimeUTC
- Flag set to assume that QuickTime date/time values are stored as UTC,
- causing conversion to local time when they are extracted. According to the
- QuickTime specification date/time values should be UTC, but many digital
- cameras store local time instead (presumably because they don't know the
- time zone), so the default is undef. This option also disables the
- autodetection of incorrect time-zero offsets in QuickTime date/time values,
- and enforces a time zero of 1904 as per the QuickTime specification.
- =item RequestAll
- Flag to request all tags to be extracted. This causes some tags to be
- generated which normally would not be unless specifically requested (by
- passing the tag name to L</ImageInfo> or L</ExtractInfo>). Note that this
- flag is set automatically during a call to L</SetNewValuesFromFile> to make
- all tags available for copying. Default is undef.
- =item RequestTags
- List of additional tags to request in next call to L</ExtractInfo>. This
- option is useful only for tags which aren't extracted unless specifically
- requested. Value may be a list reference, a delimited string of tag names
- (any delimiter is allowed), or undef to clear the current RequestTags list.
- Case is not significant. Default is undef.
- =item ScanForXMP
- Flag to scan all files (even unrecognized formats) for XMP information
- unless XMP was already found in the file. When combined with the FastScan
- option, only unrecognized file types are scanned for XMP. Default is undef.
- =item Sort
- Specifies order to sort tags in returned list:
- Input - Sort in same order as input tag arguments (default)
- File - Sort in order that tags were found in the file
- Tag - Sort alphabetically by tag name
- Descr - Sort by tag description (for current Lang setting)
- Group# - Sort by tag group, where # is zero or more family
- numbers separated by colons. If # is not specified,
- Group0 is assumed. See GetGroup for a description
- of group families.
- =item Sort2
- Secondary sort order used for tags within each group when Sort is 'Group':
- File - Sort in order tags were found in the file (default)
- Tag - Sort alphabetically by tag name
- Descr - Sort by tag description (for current Lang setting)
- =item StrictDate
- Flag to return undefined value for any date which can't be converted when
- the DateFormat option is used. Default is undef.
- =item Struct
- Flag to return XMP structures as hash references instead of flattening into
- individual tags. Has no effect when writing since both flattened and
- structured tags may always be written. Possible values are:
- undef - Same as 0 for reading, 2 for copying
- 0 - Read/copy flattened tags
- 1 - Read/copy structured tags
- 2 - Read/copy both flattened and structured tags, but flag
- flattened tags as 'unsafe' for copying
- =item SystemTags
- Flag to extract the following additional File System tags: FileAttributes,
- FileDeviceNumber, FileInodeNumber, FileHardLinks, FileUserID, FileGroupID,
- FileDeviceID, FileBlockSize and FileBlockCount.
- =item TextOut
- Output file reference for Verbose and HtmlDump options. Default is
- \*STDOUT.
- =item Unknown
- Flag to get the values of unknown tags. If set to 1, unknown tags are
- extracted from EXIF (or other tagged-format) directories. If set to 2,
- unknown tags are also extracted from binary data blocks. Default is 0.
- =item UserParam
- Special option to set/get user-defined parameters. Useful to allow external
- input into tag name expressions and ValueConv logic. I<PARAM> is the
- user-defined parameter name (case insensitive).
- PARAM - Get parameter
- PARAM= - Clear parameter
- PARAM=VALUE - Set parameter
- User-defined parameters may be accessed in tag name expressions by prefixing
- the parameter name with a dollar sign, just like normal tags. If called
- without a parameter name, C<Options('UserParam')> returns a reference to the
- hash of all user parameters (with lower-case names).
- =item Verbose
- Print verbose messages to file specified by TextOut option. Value may be
- from 0 to 5 for increasingly verbose messages. Default is 0. With the
- verbose option set, messages are printed to the console as the file is
- parsed. Level 1 prints the tag names and raw values. Level 2 adds more
- details about the tags. Level 3 adds a hex dump of the tag data, but with
- limits on the number of bytes dumped. Levels 4 and 5 remove the dump limit
- on tag values and JPEG segment data respectively.
- =item WriteMode
- Set tag write/create mode. Value is a string of one or more characters from
- list below. Default is 'wcg'.
- w - Write existing tags
- c - Create new tags
- g - create new Groups as necessary
- The level of the group differs for different types of metadata. For XMP or
- IPTC this is the full XMP/IPTC block (the family 0 group), but for EXIF this
- is the individual IFD (the family 1 group).
- =item XMPAutoConv
- Flag to enable automatic conversion for unknown XMP tags with values that
- look like rational numbers or dates. Default is 1.
- =back
- =item Return Values:
- The original value of the last specified parameter.
- =back
- =head2 ClearOptions
- Reset all options to their default values. Loads user-defined default
- option values from the %Image::ExifTool::UserDefined::Options hash in the
- .ExifTool_config file if it exists.
- $exifTool->ClearOptions();
- =over 4
- =item Inputs:
- 0) ExifTool object reference
- =item Return Values:
- (none)
- =back
- =head2 ExtractInfo
- Extract all meta information from an image.
- $success = $exifTool->ExtractInfo('image.jpg', \%options);
- =over 4
- =item Inputs:
- L</ExtractInfo> takes exactly the same arguments as L</ImageInfo>. The only
- difference is that a list of tag keys is not returned if an ARRAY reference
- is given. The following options are effective in the call to
- L</ExtractInfo>:
- Binary, Charset, CharsetEXIF, CharsetFileName, CharsetID3, CharsetIPTC,
- CharsetPhotoshop, CharsetQuickTime, Composite, ExtendedXMP, ExtractEmbedded,
- FastScan, FixBase, HtmlDump, HtmlDumpBase, IgnoreMinorErrors, Lang,
- LargeFileSupport, MakerNotes, NoPDFList, PNGEarlyXMP, ScanForXMP, Struct,
- TextOut, Unknown and Verbose.
- =item Return Value:
- 1 if this was a recognized file format, 0 otherwise (and 'Error' tag set).
- =back
- =head2 GetInfo
- L</GetInfo> is called to return meta information after it has been extracted
- from the image by a previous call to L</ExtractInfo> or L</ImageInfo>. This
- function may be called repeatedly after a single call to L</ExtractInfo> or
- L</ImageInfo>.
- # get image width and height only
- $info = $exifTool->GetInfo('ImageWidth', 'ImageHeight');
- # get all Error and Warning messages
- $info = $exifTool->GetInfo('Error', 'Warning');
- # get information for all tags in list (list updated with tags found)
- $info = $exifTool->GetInfo(\@ioTagList);
- # get all information in Author or Location groups
- $info = $exifTool->GetInfo({Group2 => ['Author', 'Location']});
- =over 4
- =item Inputs:
- Inputs are the same as L</ExtractInfo> and L</ImageInfo> except that an
- image can not be specified. Options in effect are:
- Charset, CoordFormat, DateFormat, Duplicates, Escape, Exclude, Filter,
- Group#, GlobalTimeShift, Lang, List, ListItem, ListSep, PrintConv, Sort (if
- a tag list reference is given) and StrictDate.
- =item Return Value:
- Reference to information hash, the same as with L</ImageInfo>.
- =back
- =head2 WriteInfo
- Write meta information to a file. The specified source file is rewritten to
- the same-type destination file with new information as specified by previous
- calls to L</SetNewValue>. The necessary segments and/or directories are
- created in the destination file as required to store the specified
- information. May be called repeatedly to write the same information to
- additional files without the need to call L</SetNewValue> again.
- # add information to a source file, writing output to new file
- $exifTool->WriteInfo($srcfile, $dstfile);
- # create XMP data file from scratch
- $exifTool->WriteInfo(undef, $dstfile, 'XMP');
- # overwrite file (you do have backups, right?)
- $exifTool->WriteInfo($srcfile);
- =over 4
- =item Inputs:
- 0) ExifTool object reference
- 1) Source file name, file reference, scalar reference, or undef to create a
- file from scratch. A reference to a
- L<File::RandomAccess|File::RandomAccess> object is also allowed as a source,
- but in this case the destination is not optional.
- 2) [optional] Destination file name, file reference, scalar reference, or
- undef to overwrite the original file. May be '-' to write to stdout.
- 3) [optional] Destination file type. Ignored if a source is defined.
- =item Return Value:
- 1 if file was written OK, 2 if file was written but no changes made, 0 on
- file write error.
- If an error code is returned, an Error tag is set and GetValue('Error') can
- be called to obtain the error description. A Warning tag may be set even if
- this routine is successful. Calling WriteInfo clears any pre-existing Error
- and Warning tags.
- $errorMessage = $exifTool->GetValue('Error');
- $warningMessage = $exifTool->GetValue('Warning');
- =item Notes:
- The source file name may be undefined to create a file from scratch
- (currently only XMP, MIE, ICC, VRD, DR4, EXV and EXIF files can be created
- in this way -- see L</CanCreate> for details). If undefined, the
- destination file type is required unless the type can be determined from the
- extension of the destination file name.
- If a destination file name is given, the specified file must not exist
- because an existing destination file will not be overwritten. Any new
- values for FileName, Directory or HardLink are ignored when a destination
- file name is specified.
- The destination file name may be undefined to overwrite the original file
- (make sure you have backups!). In this case, if a source file name is
- provided, a temporary file is created and renamed to replace the source file
- if no errors occurred while writing. Otherwise, if a source file reference
- or scalar reference is used, the image is first written to memory then
- copied back to replace the original if there were no errors.
- On Mac OS systems, the file resource fork is preserved if this routine is
- called with a source file name.
- =back
- The following ExifTool options are effective in the call to L</WriteInfo>:
- ByteOrder, Charset, CharsetEXIF, CharsetFileName, CharsetIPTC, Compact,
- Compress, FixBase, IgnoreMinorErrors, PNGEarlyXMP and Verbose.
- =head2 GetTagList
- Get a sorted list of tags from the specified information hash or tag list.
- @tags = $exifTool->GetTagList($info, 'Group0');
- =over 4
- =item Inputs:
- 0) ExifTool object reference
- 1) [optional] Information hash reference or tag list reference
- 2) [optional] Sort order ('Input', 'File', 'Tag', 'Descr' or 'Group#')
- 3) [optional] Secondary sort order ('File', 'Tag' or 'Descr')
- If the information hash or tag list reference is not provided, then the list
- of found tags from the last call to L</ImageInfo>, L</ExtractInfo> or
- L</GetInfo> is used instead, and the result is the same as if
- L</GetFoundTags> was called. If sort order is not specified, the sort order
- is taken from the current options settings.
- =item Return Values:
- A list of tag keys in the specified order.
- =back
- =head2 GetFoundTags
- Get list of found tags in specified sort order. The found tags are the tags
- for the information obtained from the most recent call to L</ImageInfo>,
- L</ExtractInfo> or L</GetInfo> for this object.
- @tags = $exifTool->GetFoundTags('File');
- =over 4
- =item Inputs:
- 0) ExifTool object reference
- 1) [optional] Sort order ('Input', 'File', 'Tag', 'Descr' or 'Group#')
- 2) [optional] Secondary sort order ('File', 'Tag' or 'Descr')
- If sort order is not specified, the sort order from the ExifTool options is
- used.
- =item Return Values:
- A list of tag keys in the specified order.
- =back
- =head2 GetRequestedTags
- Get list of requested tags. These are the tags that were specified in the
- arguments of the most recent call to L</ImageInfo>, L</ExtractInfo> or
- L</GetInfo>, including tags specified via a tag list reference. Shortcut
- tags are expanded in the list.
- @tags = $exifTool->GetRequestedTags();
- =over 4
- =item Inputs:
- (none)
- =item Return Values:
- List of requested tag keys in the same order that the tags were specified.
- Note that this list will be empty if tags were not specifically requested
- (ie. If extracting all tags).
- =back
- =head2 GetValue
- Get the value of a specified tag. The returned value is either the
- human-readable (PrintConv) value, the converted machine-readable (ValueConv)
- value, or the original raw (Raw) value. If the value type is not specified,
- the PrintConv value is returned if the PrintConv option is set, otherwise
- the ValueConv value is returned. The PrintConv values are same as the
- values returned by L</ImageInfo> and L</GetInfo> in the tag/value hash
- unless the PrintConv option is disabled.
- Tags which represent lists of multiple values (as may happen with 'Keywords'
- for example) are handled specially. In scalar context, the returned
- PrintConv value for these tags is either a string of values or a list
- reference (depending on the List option setting), and the ValueConv value is
- always a list reference. But in list context, L</GetValue> always returns
- the list itself.
- Note that L</GetValue> requires a case-sensitive tag key as an argument. To
- retrieve tag information based on a case-insensitive tag name (with an
- optional group specifier), use L</GetInfo> instead.
- # PrintConv example
- my $val = $exifTool->GetValue($tag);
- if (ref $val eq 'SCALAR') {
- print "$tag = (unprintable value)\n";
- } else {
- print "$tag = $val\n";
- }
- # ValueConv examples
- my $val = $exifTool->GetValue($tag, 'ValueConv');
- if (ref $val eq 'ARRAY') {
- print "$tag is a list of values\n";
- } elsif (ref $val eq 'SCALAR') {
- print "$tag represents binary data\n";
- } else {
- print "$tag is a simple scalar\n";
- }
- my @keywords = $exifTool->GetValue('Keywords', 'ValueConv');
- The following options are in effect when L</GetValue> is called:
- Charset, CoordFormat, DateFormat, Escape, Filter, GlobalTimeShift, Lang,
- List, ListItem, ListSep, PrintConv and StrictDate.
- =over 4
- =item Inputs:
- 0) ExifTool object reference
- 1) Tag key
- 2) [optional] Value type: 'PrintConv', 'ValueConv', 'Both', 'Raw' or
- 'Rational'
- The default value type is 'PrintConv' if the PrintConv option is set,
- otherwise the default is 'ValueConv'. A value type of 'Both' returns both
- ValueConv and PrintConv values as a list. 'Rational' returns the raw
- rational value as a string fraction for rational types, or undef for other
- types.
- =item Return Values:
- The value of the specified tag. If the tag represents a list of multiple
- values and the List option is disabled then PrintConv returns a string of
- values, otherwise a reference to the list is returned in scalar context.
- The list itself is returned in list context. (Unless 'Both' values are
- requested, in which case two list references are returned, regardless of
- context.) Values may also be scalar references to binary data, or hash
- references if the L</Struct> option is set.
- Note: It is possible for L</GetValue> to return an undefined ValueConv or
- PrintConv value (or an empty list in list context) even if the tag exists,
- since it is possible for these conversions to yield undefined values. And
- the Rational value will be undefined for any non-rational tag. The Raw
- value should always exist if the tag exists.
- =back
- =head2 SetNewValue
- Set the new value for a tag. The routine may be called multiple times to
- set the values of many tags before using L</WriteInfo> to write the new
- values to an image.
- For list-type tags (like Keywords), either call repeatedly with the same tag
- name for each value, or call with a reference to the list of values.
- # set a new value for a tag (errors go to STDERR)
- $success = $exifTool->SetNewValue($tag, $value);
- # set a new value and capture any error message
- ($success, $errStr) = $exifTool->SetNewValue($tag, $value);
- # delete information for specified tag if it exists in image
- # (also resets AddValue and DelValue options for this tag)
- $exifTool->SetNewValue($tag);
- # reset all values from previous calls to SetNewValue()
- $exifTool->SetNewValue();
- # delete a specific keyword
- $exifTool->SetNewValue('Keywords', $word, DelValue => 1);
- # set keywords (a list-type tag) with two new values
- $exifTool->SetNewValue(Keywords => 'word1');
- $exifTool->SetNewValue(Keywords => 'word2');
- # equivalent, but set both in one call using an array reference
- $exifTool->SetNewValue(Keywords => ['word1','word2']);
- # add a keyword without replacing existing keywords in the file
- $exifTool->SetNewValue(Keywords => $word, AddValue => 1);
- # set a tag in a specific group
- $exifTool->SetNewValue(Headline => $val, Group => 'XMP');
- $exifTool->SetNewValue('XMP:Headline' => $val); # (equivalent)
- # shift original date/time back by 2.5 hours
- $exifTool->SetNewValue(DateTimeOriginal => '2:30', Shift => -1);
- # write a tag only if it had a specific value
- # (the order of the following calls is not significant)
- $exifTool->SetNewValue(Title => $oldVal, DelValue => 1);
- $exifTool->SetNewValue(Title => $newVal);
- # write tag by numerical value
- $exifTool->SetNewValue(Orientation => 6, Type => 'ValueConv');
- $exifTool->SetNewValue('Orientation#' => 6); # (equivalent)
- # delete all but EXIF tags
- $exifTool->SetNewValue('*'); # delete all...
- $exifTool->SetNewValue('EXIF:*', undef, Replace => 2); # ...but EXIF
- # write structured information as a HASH reference
- $exifTool->SetNewValue('XMP:Flash' => {
- mode => 'on',
- fired => 'true',
- return => 'not'
- });
- # write structured information as a serialized string
- $exifTool->SetNewValue('XMP:Flash'=>'{mode=on,fired=true,return=not}');
- (See L<http://owl.phy.queensu.ca/~phil/exiftool/struct.html#Serialize> for
- a description of the structure serialization technique.)
- =over 4
- =item Inputs:
- 0) ExifTool object reference
- 1) [optional] Tag key or tag name, or undef to clear all new values. The
- tag name may be prefixed by one or more family 0, 1 or 2 group names with
- optional leading family numbers, separated by colons (eg. 'EXIF:Artist',
- 'XMP:Time:*'), which is equivalent to using a Group option argument. Also,
- a '#' may be appended to the tag name (eg. 'EXIF:Orientation#'), with the
- same effect as setting Type to 'ValueConv'. Wildcards ('*' and '?') may be
- used in the tag name to assign multiple tags simultaneously. A tag name of
- '*' is special when deleting information, and will delete an entire group
- even if some individual tags in the group are not writable, but only if a
- single family 0 or 1 group is specified (otherwise the tags are deleted
- individually). Use L</GetDeleteGroups> to get a list of deletable group
- names, and see L<Image::ExifTool::TagNames|Image::ExifTool::TagNames> for a
- complete list of tag names.
- 2) [optional] New value for tag. Undefined to delete tag from file. May be
- a scalar, scalar reference, list reference to set a list of values, or hash
- reference for a structure. Integer values may be specified as a hexadecimal
- string (with a leading '0x'), and simple rational values may be specified in
- fractional form (eg. '4/10'). Structure tags may be specified either as a
- hash reference or a serialized string (see the last two examples above).
- 3-N) [optional] SetNewValue option/value pairs (see below).
- =item SetNewValue Options:
- =over 4
- =item AddValue
- Specifies that the value be added to an existing list in a file rather than
- overwriting. Valid settings are 0 (overwrite any existing tag value), 1
- (add to an existing list and warn for non-list tags) or 2 (add to existing
- list and overwrite non-list tags). Default is 0.
- =item DelValue
- Delete existing tag from a file if it has the specified value. Option
- values are 0 or 1. Default is 0.
- =item EditGroup
- Create tags in existing groups only. Don't create new group. Valid values
- are 0 and 1. Effectively removes the 'g' from the ExifTool WriteMode option
- for this tag only. Default is 0.
- =item EditOnly
- Edit tag only if it already exists. Don't create new tag. Valid values are
- 0 and 1. Effectively removes the 'c' from the ExifTool WriteMode option for
- this tag only. Default is 0.
- =item Group
- Specifies group name where tag should be written. If not specified, tag is
- written to highest priority group as specified by L</SetNewGroups>. May be
- one or more family 0, 1 or 2 groups with optional leading family number,
- separated by colons. Case is not significant.
- =item NoFlat
- Treat flattened tags as 'unsafe'.
- =item NoShortcut
- Disables default behaviour of looking up tag in shortcuts if not found
- otherwise.
- =item Protected
- Bit mask for tag protection levels to write. Bit 0x01 allows writing of
- 'unsafe' tags (ie. tags not copied automatically via
- L</SetNewValuesFromFile>). Bit 0x02 allows writing of 'protected' tags, and
- should only be used internally by ExifTool. See
- L<Image::ExifTool::TagNames|Image::ExifTool::TagNames>, for a list of tag
- names indicating 'unsafe' and 'protected' tags. Default is 0.
- =item ProtectSaved
- Avoid setting new values which were saved after the Nth call to
- L</SaveNewValues>. Has no effect on unsaved values, or values saved before
- Nth call. Option value is N. Default is undef.
- =item Replace
- Flag to replace the previous new values for this tag (ie. replace the values
- set in previous calls to L</SetNewValue>). This option is most commonly
- used to replace previously-set new values for list-type tags. Valid values
- are 0 (set new value normally -- adds to new values for list-type tags), 1
- (reset previous new values for this tag and replace with the specified new
- value) or 2 (reset previous new values only).
- =item Shift
- Shift the tag by the specified value. Currently only date/time tags and
- tags with numerical values may be shifted. Undefined for no shift, 1 for a
- positive shift, or -1 for a negative shift. A value of 0 causes a positive
- shift to be applied if the tag is shiftable and AddValue is set, or a
- negative shift for date/time tags only if DelValue is set. Default is undef.
- See L<Image::ExifTool::Shift.pl|Image::ExifTool::Shift.pl> for more
- information.
- =item Type
- The type of value being set. Valid values are PrintConv, ValueConv or Raw.
- Default is PrintConv if the L</PrintConv> Option is set, otherwise
- ValueConv.
- =back
- =item Return Values:
- In scalar context, returns the number of tags set and error messages are
- printed to STDERR. In list context, returns the number of tags set, and the
- error string (which is undefined if there was no error).
- =item Notes:
- When deleting groups of tags, the Replace option may be used to exclude
- specific groups from a mass delete. However, this technique may not be used
- to exclude individual tags from a group delete (unless a family 2 group was
- specified in the delete). Instead, use L</SetNewValuesFromFile> to recover
- the values of individual tags after deleting a group.
- When deleting all tags from a JPEG image, the APP14 "Adobe" information is
- not deleted by default because doing so may affect the appearance of the
- image. However, this information may be deleted by specifying it
- explicitly, either by group (with 'Adobe:*') or as a block (with 'Adobe').
- =back
- The following ExifTool options are effective in the call to L</SetNewValue>:
- Charset, Escape, IgnoreMinorErrors, Lang, ListSep, ListSplit, PrintConv,
- Verbose and WriteMode.
- =head2 GetNewValue
- Get the new Raw value for a tag. This is the value set by L</SetNewValue>
- this is queued to be written to file. List-type tags may return multiple
- values in list context.
- $rawVal = $exifTool->GetNewValue($tag);
- @rawVals = $exifTool->GetNewValue($tag);
- =over 4
- =item Inputs:
- 0) ExifTool object reference
- 1) Tag name (case sensitive, may be prefixed by family 0 or 1 group name)
- =item Return Values:
- List of new Raw tag values, or first value in list when called in scalar
- context. The list may be empty either if the tag isn't being written, or if
- it is being deleted (ie. if L</SetNewValue> was called without a value).
- =back
- =head2 SetNewValuesFromFile
- A very powerful routine that sets new values for tags from information found
- in a specified file.
- # set new values from all information in a file...
- my $info = $exifTool->SetNewValuesFromFile($srcFile);
- # ...then write these values to another image
- my $result = $exifTool->WriteInfo($file2, $outFile);
- # set all new values, preserving original groups
- $exifTool->SetNewValuesFromFile($srcFile, '*:*');
- # set specific information
- $exifTool->SetNewValuesFromFile($srcFile, @tags);
- # set new value from a different tag in specific group
- $exifTool->SetNewValuesFromFile($fp, 'IPTC:Keywords>XMP-dc:Subject');
- # add all IPTC keywords to XMP subject list
- $exifTool->SetNewValuesFromFile($fp, 'IPTC:Keywords+>XMP-dc:Subject');
- # set new value from an expression involving other tags
- $exifTool->SetNewValuesFromFile($file,
- 'Comment<ISO=$ISO Aperture=$aperture Exposure=$shutterSpeed');
- # set keywords list from the values of multiple tags
- $exifTool->SetNewValuesFromFile($file, { Replace => 0 },
- 'keywords<xmp:subject', 'keywords<filename');
- # copy all EXIF information, preserving the original IFD
- # (without '>*.*' tags would be copied to the preferred EXIF IFD)
- $exifTool->SetNewValuesFromFile($file, 'EXIF:*>*:*');
- # copy all tags with names starting with "gps" (note: this is
- # different than "gps:*" because it will also copy XMP GPS tags)
- $exifTool->SetNewValuesFromFile($file, 'gps*');
- # set FileName from Model, translating questionable characters
- $exifTool->SetNewValuesFromFile($file,
- 'filename<${model; tr(/\\\\?*:|"><)(_) }.jpg');
- =over 4
- =item Inputs:
- 0) ExifTool object reference
- 1) File name, file reference, or scalar reference
- 2-N) [optional] List of tag names to set or options hash references. All
- writable tags are set if none are specified. The tag names are not case
- sensitive, and may be prefixed by one or more family 0, 1 or 2 group names with
- optional leading family numbers, separated by colons (eg. 'exif:iso'). A
- leading '-' indicates tags to be excluded (eg. '-comment'), or a trailing '#'
- causes the ValueConv value to be copied (same as setting the Type option to
- 'ValueConv' for this tag only). Wildcards ('*' and '?') may be used in the tag
- name. A tag name of '*' is commonly used when a group is specified to copy all
- tags in the group (eg. 'XMP:*'). A special feature allows tag names of the form
- 'DSTTAGE<lt>SRCTAG' (or 'SRCTAGE<gt>DSTTAG') to be specified to copy information
- to a tag with a different name or a specified group. Both 'SRCTAG' and 'DSTTAG'
- may contain wildcards and/or be prefixed by a group name (eg.
- 'fileModifyDateE<lt>modifyDate' or 'xmp:*E<lt>*'), and/or suffixed by a '#' to
- disable print conversion. Copied tags may also be added or deleted from a list
- with arguments of the form 'DSTTAG+E<lt>SRCTAG' or 'DSTTAG-E<lt>SRCTAG'. Tags
- are evaluated in order, so exclusions apply only to tags included earlier in the
- list. An extension of this feature allows the tag value to be set from an
- expression containing tag names with leading '$' symbols (eg. 'CommentE<lt>the
- file is $filename'). Braces '{}' may be used around the tag name to separate it
- from subsequent text, and a '$$' is used to to represent a '$' symbol. The
- behaviour for missing tags in expressions is defined by the L</MissingTagValue>
- option. The tag value may be modified via changes to the default input variable
- ($_) in Perl expressions placed inside the braces and after a semicolon
- following the tag name. Braces within the expression must be balanced.
- Multiple options hash references may be passed to set different options for
- different tags. Options apply to subsequent tags in the argument list.
- By default, this routine will commute information between same-named tags in
- different groups, allowing information to be translated between images with
- different formats. This behaviour may be modified by specifying a group
- name for extracted tags (even if '*' is used as a group name), in which case
- the information is written to the original group, unless redirected to a
- different group. When '*' is used for a group name, by default the family 1
- group of the original tag is preserved, but a different family may be specified
- with a leading family number. (For example, specifying '*:*' copies all
- information while preserving the original family 1 groups, while '0*:*'
- preserves the family 0 group.)
- =item SetNewValuesFromFile Options:
- The options are the same was for L</SetNewValue>, and are passed directly
- to L</SetNewValue> internally, with a few exceptions:
- - The Replace option defaults to 1 instead of 0 as with L</SetNewValue>.
- - The AddValue or DelValue option is set for individual tags if '+>' or '->'
- (or '+E<lt>' or '-E<lt>') are used.
- - The Group option is set for tags where a group name is given.
- - The Protected flag is set to 1 for individually specified tags.
- - The Type option also applies to extracted tags.
- =item Return Values:
- A hash of information that was set successfully. May include Warning or
- Error entries if there were problems reading the input file.
- =item Notes:
- The PrintConv option applies to this routine, but it normally should be left
- on to provide more reliable transfer of information between groups.
- If a preview image exists, it is not copied. The preview image must be
- transferred separately if desired, in a separate call to L</WriteInfo>
- When simply copying all information between files of the same type, it is
- usually desirable to preserve the original groups by specifying '*:*' for
- the tags to set.
- The L</Duplicates> option is always in effect for tags extracted from the
- source file using this routine.
- The L</Struct> option is enabled by default for tags extracted by this
- routine. This allows the hierarchy of complex structures to be preserved
- when copying, but the Struct option may be set to 0 to override this
- behaviour and copy as flattened tags instead.
- =back
- =head2 CountNewValues
- Return the total number of new values set.
- $numSet = $exifTool->CountNewValues();
- ($numSet, $numPseudo) = $exifTool->CountNewValues();
- =over 4
- =item Inputs:
- 0) ExifTool object reference
- =item Return Values:
- In scalar context, returns the total number of tags with new values set. In
- list context, also returns the number of "pseudo" tag values which have been
- set. "Pseudo" tags are tags like FileName and FileModifyDate which are not
- contained within the file and can be changed without rewriting the file.
- =back
- =head2 SaveNewValues
- Save state of new values to be later restored by L</RestoreNewValues>.
- $exifTool->SaveNewValues(); # save state of new values
- $exifTool->SetNewValue(ISO => 100); # set new value for ISO
- $exifTool->WriteInfo($src, $dst1); # write ISO + previous new values
- $exifTool->RestoreNewValues(); # restore previous new values
- $exifTool->WriteInfo($src, $dst2); # write previous new values only
- =over 4
- =item Inputs:
- 0) ExifTool object reference
- =item Return Value:
- Count of the number of times this routine has been called (N) since the last
- time the new values were reset.
- =back
- =head2 RestoreNewValues
- Restore new values to the settings that existed when L</SaveNewValues> was
- last called. May be called repeatedly after a single call to
- L</SaveNewValues>. See L</SaveNewValues> above for an example.
- =over 4
- =item Inputs:
- 0) ExifTool object reference
- =item Return Value:
- None.
- =back
- =head2 SetFileModifyDate
- Write the filesystem modification or creation time from the new value of the
- FileModifyDate or FileCreateDate tag.
- $exifTool->SetNewValue(FileModifyDate => '2000:01:02 03:04:05-05:00',
- Protected => 1);
- $result = $exifTool->SetFileModifyDate($file);
- =over 4
- =item Inputs:
- 0) ExifTool object reference
- 1) File name
- 2) [optional] Base time if applying shift (days before $^T)
- 3) [optional] Tag to write: 'FileModifyDate' (default), or 'FileCreateDate'
- =item Return Value:
- 1 if the time was changed, 0 if nothing was done, or -1 if there was an
- error setting the time.
- =item Notes:
- Equivalent to, but more efficient than calling L</WriteInfo> when only the
- FileModifyDate or FileCreateDate tag has been set. If a timezone is not
- specified, local time is assumed. When shifting, the time of the original
- file is used unless the optional base time is specified.
- The ability to write FileCreateDate is currently restricted to Windows
- systems only.
- =back
- =head2 SetFileName
- Set the file name and directory, or create a hard link. If not specified,
- the new file name is derived from the new values of the FileName and
- Directory tags, or from the HardLink tag if creating a link. If the
- FileName tag contains a '/', then the file is renamed into a new directory.
- If FileName ends with '/', then it is taken as a directory name and the file
- is moved into the new directory. The new value for the Directory tag takes
- precedence over any directory specified in FileName.
- $result = $exifTool->SetFileName($file);
- $result = $exifTool->SetFileName($file, $newName);
- =over 4
- =item Inputs:
- 0) ExifTool object reference
- 1) Current file name
- 2) [optional] New file name
- 3) [optional] 'Link' to create a hard link instead of renaming the file, or
- 'Test' to test renaming feature by printing the old and new names instead of
- changing anything.
- =item Return Value:
- 1 if the file name or directory was changed, 0 if nothing was done, or -1 if
- there was an error renaming the file.
- =item Notes:
- Will not overwrite existing files. New directories are created as necessary.
- =back
- =head2 SetNewGroups
- Set the order of the preferred groups when adding new information. In
- subsequent calls to L</SetNewValue>, new information will be created in the
- first valid group of this list. This has an impact only if the group is not
- specified when calling L</SetNewValue> and if the tag name exists in more
- than one group. The default order is EXIF, IPTC then XMP. Any family 0
- group name may be used. Case is not significant.
- $exifTool->SetNewGroups('XMP','EXIF','IPTC');
- =over 4
- =item Inputs:
- 0) ExifTool object reference
- 1-N) Groups in order of priority. If no groups are specified, the priorities
- are reset to the defaults.
- =item Return Value:
- None.
- =back
- =head2 GetNewGroups
- Get current group priority list.
- @groups = $exifTool->GetNewGroups();
- =over 4
- =item Inputs:
- 0) ExifTool object reference
- =item Return Values:
- List of group names in order of write priority. Highest priority first.
- =back
- =head2 GetTagID
- Get the ID for the specified tag. The ID is the IFD tag number in EXIF
- information, the property name in XMP information, or the data offset in a
- binary data block. For some tags, such as Composite tags where there is no
- ID, an empty string is returned. In list context, also returns a language
- code for the tag if available and different from the default language (eg.
- with alternate language entries for XMP "lang-alt" tags).
- $id = $exifTool->GetTagID($tag);
- ($id, $lang) = $exifTool->GetTagID($tag);
- =over 4
- =item Inputs:
- 0) ExifTool object reference
- 1) Tag key
- =item Return Values:
- In scalar context, returns the tag ID or '' if there is no ID for this tag.
- In list context, returns the tag ID (or '') and the language code (or
- undef).
- =back
- =head2 GetDescription
- Get description for specified tag. This function will always return a
- defined value. In the case where the description doesn't exist, one is
- generated from the tag name.
- =over 4
- =item Inputs:
- 0) ExifTool object reference
- 1) Tag key
- =item Return Values:
- A description for the specified tag.
- =back
- =head2 GetGroup
- Get group name(s) for a specified tag.
- # return family 0 group name (eg. 'EXIF');
- $group = $exifTool->GetGroup($tag, 0);
- # return all groups (eg. qw{EXIF IFD0 Author Main})
- @groups = $exifTool->GetGroup($tag);
- # return groups as a string (eg. 'Main:IFD0:Author')
- $group = $exifTool->GetGroup($tag, ':3:1:2');
- # return groups as a simplified string (eg. 'IFD0:Author')
- $group = $exifTool->GetGroup($tag, '3:1:2');
- =over 4
- =item Inputs:
- 0) ExifTool object reference
- 1) Tag key
- 2) [optional] Group family number, or string of numbers separated by colons
- =item Return Values:
- Group name (or '' if tag has no group). If no group family is specified,
- L</GetGroup> returns the name of the group in family 0 when called in scalar
- context, or the names of groups for all families in list context. Returns a
- string of group names separated by colons if the input group family contains
- a colon. The string is simplified to remove a leading 'Main:' and adjacent
- identical group names unless the family string begins with a colon.
- =item Notes:
- The group family numbers are currently available:
- 0) Information Type (eg. EXIF, XMP, IPTC)
- 1) Specific Location (eg. IFD0, XMP-dc)
- 2) Category (eg. Author, Time)
- 3) Document Number (eg. Main, Doc1, Doc3-2)
- 4) Instance Number (eg. Copy1, Copy2, Copy3...)
- Families 0 and 1 are based on the file structure, and are similar except
- that family 1 is more specific and sub-divides some groups to give more
- detail about the specific location where the information was found. For
- example, the EXIF group is split up based on the specific IFD (Image File
- Directory), the MakerNotes group is divided into groups for each
- manufacturer, and the XMP group is separated based on the XMP namespace
- prefix. Note that only common XMP namespaces are listed in the
- L<GetAllGroups documentation|/GetAllGroups [static]>, but additional
- namespaces may be present in some XMP data. Also note that the 'XMP-xmp...'
- group names may appear in the older form 'XMP-xap...' since these names
- evolved as the XMP standard was developed. The ICC_Profile group is broken
- down to give information about the specific ICC_Profile tag from which
- multiple values were extracted. As well, information extracted from the
- ICC_Profile header is separated into the ICC-header group.
- Family 2 classifies information based on the logical category to which the
- information refers.
- Family 3 gives the document number for tags extracted from embedded
- documents, or 'Main' for tags from the main document. (See the
- L</ExtractEmbedded> option for extracting tags from embedded documents.)
- Nested sub-documents (if they exist) are indicated by numbers separated with
- dashes in the group name, to an arbitrary depth. (eg. 'Doc2-3-1' is the 1st
- sub-sub-document of the 3rd sub-document of the 2nd embedded document of the
- main file.)
- Family 4 provides a method for differentiating tags when multiple tags exist
- with the same name in the same location. The primary instance of a tag (the
- tag extracted when the Duplicates option is disabled and no group is
- specified) has no family 4 group name, but additional instances have have
- family 4 group names of 'Copy1', 'Copy2', 'Copy3', etc.
- See L</GetAllGroups [static]> for complete lists of group names.
- =back
- =head2 GetGroups
- Get list of group names that exist in the specified information.
- @groups = $exifTool->GetGroups($info, 2);
- @groups = $exifTool->GetGroups('3:1');
- =over 4
- =item Inputs:
- 0) ExifTool object reference
- 1) [optional] Info hash ref (default is all extracted info)
- 2) [optional] Group family number, or string of numbers (default 0)
- =item Return Values:
- List of group names in alphabetical order. If information hash is not
- specified, the group names are returned for all extracted information. See
- L</GetGroup> for an description of family numbers and family number strings.
- =back
- =head2 BuildCompositeTags
- Builds composite tags from required tags. The composite tags are
- convenience tags which are derived from the values of other tags. This
- routine is called automatically by L</ImageInfo> and L</ExtractInfo> if the
- Composite option is set.
- =over 4
- =item Inputs:
- 0) ExifTool object reference
- =item Return Values:
- (none)
- =item Notes:
- Tag values are calculated in alphabetical order unless a tag Require's or
- Desire's another composite tag, in which case the calculation is deferred
- until after the other tag is calculated.
- Composite tags may need to read data from the image for their value to be
- determined, and for these L</BuildCompositeTags> must be called while the
- image is available. This is only a problem if L</ImageInfo> is called with
- a filename (as opposed to a file reference or scalar reference) since in
- this case the file is closed before L</ImageInfo> returns. Here the
- Composite option may be used so that L</BuildCompositeTags> is called from
- within L</ImageInfo>, before the file is closed.
- =back
- =head2 GetTagName [static]
- Get name of tag from tag key. This is a convenience function that
- strips the embedded instance number, if it exists, from the tag key.
- Note: "static" in the heading above indicates that the function does not
- require an ExifTool object reference as the first argument. All functions
- documented below are also static.
- $tagName = Image::ExifTool::GetTagName($tag);
- =over 4
- =item Inputs:
- 0) Tag key
- =item Return Value:
- Tag name. This is the same as the tag key but has the instance number
- removed.
- =back
- =head2 GetShortcuts [static]
- Get a list of shortcut tags.
- =over 4
- =item Inputs:
- (none)
- =item Return Values:
- List of shortcut tags (as defined in Image::ExifTool::Shortcuts).
- =back
- =head2 GetAllTags [static]
- Get list of all available tag names.
- @tagList = Image::ExifTool::GetAllTags($group);
- =over 4
- =item Inputs:
- 0) [optional] Group name, or string of group names separated by colons
- =item Return Values:
- A list of all available tags in alphabetical order, or all tags in a
- specified group or intersection of groups. The group name is case
- insensitive, and any group in families 0-2 may be used except for EXIF
- family 1 groups (ie. the specific IFD).
- =back
- =head2 GetWritableTags [static]
- Get list of all writable tag names.
- @tagList = Image::ExifTool::GetWritableTags($group);
- =over 4
- =item Inputs:
- 0) [optional] Group name, or string of group names separated by colons
- =item Return Values:
- A list of all writable tags in alphabetical order. These are the tags for
- which values may be set through L</SetNewValue>. If a group name is given,
- returns only writable tags in specified group(s). The group name is case
- insensitive, and any group in families 0-2 may be used except for EXIF
- family 1 groups (ie. the specific IFD).
- =back
- =head2 GetAllGroups [static]
- Get list of all group names in specified family.
- @groupList = Image::ExifTool::GetAllGroups($family);
- =over 4
- =item Inputs:
- 0) Group family number (0-4)
- =item Return Values:
- A list of all groups in the specified family in alphabetical order.
- =back
- Here is a complete list of groups for each of these families:
- =over 4
- =item Family 0 (Information Type):
- AFCP, AIFF, APE, APP0, APP1, APP11, APP12, APP13, APP14, APP15, APP4, APP5,
- APP6, APP8, ASF, Audible, CanonVRD, Composite, DICOM, DNG, DV, DjVu, Ducky,
- EXE, EXIF, ExifTool, FLAC, FLIR, File, Flash, FlashPix, Font, FotoStation,
- GIF, GIMP, GeoTiff, H264, HTML, ICC_Profile, ID3, IPTC, ITC, JFIF, JPEG,
- Jpeg2000, LNK, Leaf, Lytro, M2TS, MIE, MIFF, MNG, MOI, MPC, MPEG, MPF, MXF,
- MakerNotes, Matroska, Meta, Ogg, OpenEXR, PDF, PICT, PLIST, PNG, PSP, Palm,
- PanasonicRaw, PhotoCD, PhotoMechanic, Photoshop, PostScript, PrintIM,
- QuickTime, RAF, RIFF, RSRC, RTF, Radiance, Rawzor, Real, SVG, SigmaRaw,
- Stim, Theora, Torrent, VCard, Vorbis, XML, XMP, ZIP
- =item Family 1 (Specific Location):
- AC3, AFCP, AIFF, APE, ASF, AVI1, Adobe, AdobeCM, AdobeDNG, Apple, Audible,
- CIFF, Canon, CanonCustom, CanonRaw, CanonVRD, Casio, Chapter#, Composite,
- DICOM, DNG, DV, DjVu, DjVu-Meta, Ducky, EPPIM, EXE, EXIF, ExifIFD, ExifTool,
- FLAC, FLIR, File, Flash, FlashPix, Font, FotoStation, FujiFilm, FujiIFD, GE,
- GIF, GIMP, GPS, GeoTiff, GlobParamIFD, GraphConv, H264, HP, HTC, HTML,
- HTML-dc, HTML-ncc, HTML-office, HTML-prod, HTML-vw96, HTTP-equiv, ICC-chrm,
- ICC-clrt, ICC-header, ICC-meas, ICC-meta, ICC-view, ICC_Profile,
- ICC_Profile#, ID3, ID3v1, ID3v1_Enh, ID3v2_2, ID3v2_3, ID3v2_4, IFD0, IFD1,
- IPTC, IPTC#, ITC, InteropIFD, JFIF, JPEG, JPEG-HDR, JVC, Jpeg2000, KDC_IFD,
- Kodak, KodakBordersIFD, KodakEffectsIFD, KodakIFD, KyoceraRaw, LNK, Leaf,
- LeafSubIFD, Leica, Lytro, M2TS, MAC, MIE-Audio, MIE-Camera, MIE-Canon,
- MIE-Doc, MIE-Extender, MIE-Flash, MIE-GPS, MIE-Geo, MIE-Image, MIE-Lens,
- MIE-Main, MIE-MakerNotes, MIE-Meta, MIE-Orient, MIE-Preview, MIE-Thumbnail,
- MIE-UTM, MIE-Unknown, MIE-Video, MIFF, MNG, MOBI, MOI, MPC, MPEG, MPF0,
- MPImage, MXF, MakerNotes, MakerUnknown, Matroska, MediaJukebox, MetaIFD,
- Microsoft, Minolta, MinoltaRaw, Motorola, NITF, Nikon, NikonCapture,
- NikonCustom, NikonScan, Nintendo, Ocad, Ogg, Olympus, OpenEXR, PDF, PICT,
- PNG, PNG-pHYs, PSP, Palm, Panasonic, PanasonicRaw, Pentax, PhaseOne,
- PhotoCD, PhotoMechanic, Photoshop, PictureInfo, PostScript, PreviewIFD,
- PrintIM, ProfileIFD, Qualcomm, QuickTime, RAF, RAF2, RIFF, RMETA, RSRC, RTF,
- Radiance, Rawzor, Real, Real-CONT, Real-MDPR, Real-PROP, Real-RA3, Real-RA4,
- Real-RA5, Real-RJMD, Reconyx, Ricoh, SPIFF, SR2, SR2DataIFD, SR2SubIFD,
- SRF#, SVG, Samsung, Sanyo, Scalado, Sigma, SigmaRaw, Sony, SonyIDC, Stim,
- SubIFD, System, Theora, Torrent, Track#, VCard, VCalendar, Version0, Vorbis,
- XML, XMP, XMP-DICOM, XMP-GPano, XMP-MP, XMP-MP1, XMP-PixelLive, XMP-aas,
- XMP-acdsee, XMP-album, XMP-apple-fi, XMP-aux, XMP-cc, XMP-cell, XMP-crs,
- XMP-dc, XMP-dex, XMP-digiKam, XMP-dwc, XMP-exif, XMP-exifEX,
- XMP-expressionmedia, XMP-extensis, XMP-fpv, XMP-getty, XMP-ics,
- XMP-iptcCore, XMP-iptcExt, XMP-lr, XMP-mediapro, XMP-microsoft,
- XMP-mwg-coll, XMP-mwg-kw, XMP-mwg-rs, XMP-pdf, XMP-pdfx, XMP-photomech,
- XMP-photoshop, XMP-plus, XMP-prism, XMP-prl, XMP-pur, XMP-rdf, XMP-swf,
- XMP-tiff, XMP-x, XMP-xmp, XMP-xmpBJ, XMP-xmpDM, XMP-xmpMM, XMP-xmpNote,
- XMP-xmpPLUS, XMP-xmpRights, XMP-xmpTPg, ZIP
- =item Family 2 (Category):
- Audio, Author, Camera, Document, ExifTool, Image, Location, Other, Preview,
- Printing, Time, Unknown, Video
- =item Family 3 (Document Number):
- Doc#, Main
- =item Family 4 (Instance Number):
- Copy#
- =back
- =head2 GetDeleteGroups [static]
- Get list of all deletable group names.
- @delGroups = Image::ExifTool::GetDeleteGroups();
- =over 4
- =item Inputs:
- None.
- =item Return Values:
- A list of deletable group names in alphabetical order. The current list of
- deletable group names is:
- AFCP, APP0, APP1, APP10, APP11, APP12, APP13, APP14, APP15, APP2, APP3,
- APP4, APP5, APP6, APP7, APP8, APP9, Adobe, CIFF, CanonVRD, Ducky, EXIF,
- ExifIFD, File, FlashPix, FotoStation, GPS, GlobParamIFD, ICC_Profile, IFD0,
- IFD1, IPTC, InteropIFD, JFIF, Jpeg2000, MIE, MPF, MakerNotes, Meta, MetaIFD,
- NikonCapture, PDF, PDF-update, PNG, PhotoMechanic, Photoshop, PrintIM,
- RMETA, RSRC, SubIFD, Trailer, XML, XML-*, XMP, XMP-*
- All names in this list are either family 0 or family 1 group names, with the
- exception of 'Trailer' which allows all trailers in JPEG and TIFF-format
- images to be deleted at once, including unknown trailers. To schedule a
- group for deletion, call L</SetNewValue> with an undefined value and a tag
- name like 'Trailer:*'.
- Note that the JPEG "APP" groups are special, and are used only to delete
- application segments which are not associated with another deletable group.
- For example, deleting 'APP14:*' will delete other APP14 segments, but not
- the APP14 "Adobe" segment.
- =back
- =head2 GetFileType [static]
- Get type of file given file name.
- my $type = Image::ExifTool::GetFileType($filename);
- my $desc = Image::ExifTool::GetFileType($filename, 1);
- =over 4
- =item Inputs:
- 0) [optional] File name (or just an extension)
- 1) [optional] Flag to return a description instead of a type. Set to 0 to
- return type for recognized but unsupported files (otherwise the return value
- for unsupported files is undef).
- =item Return Value:
- A string, based on the file extension, which indicates the basic format of
- the file. Note that some files may be based on other formats (like many RAW
- image formats are based on TIFF). In array context, may return more than
- one file type if the file may be based on different formats. Returns undef
- if files with this extension are not yet supported by ExifTool. Returns a
- list of extensions for all supported file types if no input extension is
- specified (or all recognized file types if the description flag is set to 0).
- Returns a more detailed description of the specific file format when the
- description flag is set.
- =back
- =head2 CanWrite [static]
- Can the specified file be written?
- my $writable = Image::ExifTool::CanWrite($filename);
- =over 4
- =item Inputs:
- 0) File name or extension
- =item Return Value:
- True if ExifTool supports writing files of this type (based on the file
- extension).
- =back
- =head2 CanCreate [static]
- Can the specified file be created?
- my $creatable = Image::ExifTool::CanCreate($filename);
- =over 4
- =item Inputs:
- 0) File name or extension
- =item Return Value:
- True if ExifTool can create files with this extension from scratch.
- Currently, this can only be done with XMP, MIE, ICC, VRD, DR4, EXV and EXIF
- files.
- =back
- =head2 AddUserDefinedTags [static]
- Add user-defined tags to an existing tag table at run time. This differs
- from the usual technique of creating user-defined tags via the
- %Image::ExifTool::UserDefined hash (see the ExifTool_config file in the
- Image::ExifTool distribution) because it allows tags to be added after the
- tag table has been initialized.
- use Image::ExifTool ':Public';
- my %tags = (
- TestTagID1 => { Name => 'TestTagName1' },
- TestTagID2 => { Name => 'TestTagName2' },
- );
- my $num = AddUserDefinedTags('Image::ExifTool::PDF::Info', %tags);
- =over 4
- =item Inputs:
- 0) Destination tag table name
- 1-N) Pairs of tag ID / tag information hash references for the new tags
- =item Return Value:
- The number of tags added.
- =item Notes
- Pre-existing tags with the same ID will be replaced in the destination
- table. See lib/Image/ExifTool/README in the full distribution for full
- details on the elements of the tag information hash.
- =back
- =head1 CHARACTER ENCODINGS
- Certain meta information formats allow coded character sets other than plain
- ASCII. When reading, most known encodings are converted to the external
- character set according to the L</Charset> option, or to UTF-8 by default.
- When writing, the inverse conversions are performed. Alternatively, special
- characters may be converted to/from HTML character entities with the
- L</Escape> HTML option.
- A distinction is made between the external character set visible via the
- ExifTool API, and the internal character used to store text in the metadata
- of a file. These character sets may be specified separately as follows:
- =over 4
- =item External Character Sets:
- The encoding for tag values passed to/from ExifTool API functions is set via
- the L</Charset> option, which is 'UTF8' by default.
- The encoding of file names is specified via the L</CharsetFileName> option.
- By default, L</CharsetFileName> is not defined, and file names passed to
- ExifTool are used directly in calls to the system i/o routines (which expect
- UTF-8 strings on Mac/Linux, but default to the system code page on Windows).
- Setting L</CharsetFileName> causes file names to be converted from the
- specified encoding to one appropriate for the system. In Windows this also
- has the effect of activating Unicode filename support via the special
- Windows wide-character i/o routines if Win32API::File is available.
- =item Internal Character Sets:
- The encodings used to store strings in the various metadata formats. These
- encodings may be changed for certain types of metadata via the
- L</CharsetEXIF>, L</CharsetID3>, L</CharsetIPTC>, L</CharsetPhotoshop> and
- L</CharsetQuickTime> options.
- =back
- Values are returned as byte strings of encoded characters. Perl wide
- characters are not used. By default, most returned strings are encoded in
- UTF-8. For these, Encode::decode_utf8() may be used to convert to a
- sequence of logical Perl characters. Note that some settings of the
- PERL_UNICODE environment variable may be incompatible with ExifTool's
- character handling.
- More specific details are given below about how character coding is handled
- for EXIF, IPTC, XMP, PNG, ID3, PDF, Photoshop, QuickTime, AIFF, MIE and
- Vorbis information:
- =head2 EXIF
- Most textual information in EXIF is stored in ASCII format (called "string"
- in the L<ExifTool tag name documentation|Image::ExifTool::TagNames>). By
- default ExifTool does not convert these strings. However, it is not
- uncommon for applications to write UTF-8 or other encodings where ASCII is
- expected. To deal with these, ExifTool allows the internal EXIF string
- encoding to be specified with L</CharsetEXIF>, which causes EXIF string
- values to be converted from the specified character set when reading, and
- stored with this character set when writing. (The MWG recommends using
- UTF-8 encoding for EXIF strings, and in keeping with this the
- L<MWG|Image::ExifTool::MWG> module sets the default internal EXIF string
- encoding to UTF-8, but note that this will have no effect unless the
- external encoding is also set to something other than the default of UTF-8.)
- A few EXIF tags (UserComment, GPSProcessingMethod and GPSAreaInformation)
- support a designated internal text encoding, with values stored as ASCII,
- Unicode (UCS-2) or JIS. When reading these tags, ExifTool converts Unicode
- and JIS to the external character set specified by the L</Charset>
- option, or to UTF-8 by default. ASCII text is not converted. When writing,
- text is stored as ASCII unless the string contains special characters, in
- which case it is converted from the external character set (UTF-8 by
- default), and stored as Unicode. ExifTool writes Unicode in native EXIF byte
- ordering by default, but the byte order may be specified by setting the
- ExifUnicodeByteOrder tag (see the
- L<Extra Tags documentation|Image::ExifTool::TagNames/Extra Tags>).
- The EXIF "XP" tags (XPTitle, XPComment, etc) are always stored as
- little-endian Unicode (UCS-2), and are read and written using the specified
- character set.
- =head2 IPTC
- The value of the IPTC:CodedCharacterSet tag determines how the internal IPTC
- string values are interpreted. If CodedCharacterSet exists and has a value
- of 'UTF8' (or 'ESC % G') then string values are assumed to be stored as
- UTF-8, otherwise Windows Latin1 (cp1252, 'Latin') coding is assumed by
- default, but this can be changed with the L</CharsetIPTC> option. When
- reading, these strings are converted to the character set specified by the
- L</Charset> option. When writing, the inverse conversions are performed.
- No conversion is done if the internal (IPTC) and external (ExifTool)
- character sets are the same. Note that ISO 2022 character set shifting is
- not supported. Instead, a warning is issued and the string is not converted
- if an ISO 2022 shift code is encountered. See L<http://www.iptc.org/IIM/>
- for the official IPTC specification.
- ExifTool may be used to convert IPTC values to a different internal
- encoding. To do this, all IPTC tags must be rewritten along with the
- desired value of CodedCharacterSet. For example, the following command
- changes the internal IPTC encoding to UTF-8 (from Windows Latin1 unless
- CodedCharacterSet was already 'UTF8'):
- exiftool -tagsfromfile @ -iptc:all -codedcharacterset=utf8 a.jpg
- or from Windows Latin2 (cp1250) to UTF-8:
- exiftool -tagsfromfile @ -iptc:all -codedcharacterset=utf8 \
- -charset iptc=latin2 a.jpg
- and this command changes it back from UTF-8 to Windows Latin1 (cp1252):
- exiftool -tagsfromfile @ -iptc:all -codedcharacterset= a.jpg
- or to Windows Latin2:
- exiftool -tagsfromfile @ -iptc:all -codedcharacterset= \
- -charset iptc=latin2 a.jpg
- Unless CodedCharacterSet is 'UTF8', applications have no reliable way to
- determine the IPTC character encoding. For this reason, it is recommended
- that CodedCharacterSet be set to 'UTF8' when creating new IPTC.
- (Note: Here, "IPTC" Refers to the older IPTC IIM format. The more recent
- IPTC Core and Extension specifications actually use the XMP format.)
- =head2 XMP
- Exiftool reads XMP encoded as UTF-8, UTF-16 or UTF-32, and converts them all
- to UTF-8 internally. Also, all XML character entity references and numeric
- character references are converted. When writing, ExifTool always encodes
- XMP as UTF-8, converting the following 5 characters to XML character
- references: E<amp> E<lt> E<gt> E<39> E<quot>. By default no further
- conversion is performed, however if the L</Charset> option is other than
- 'UTF8' then text is converted to/from a specified character set when
- reading/writing.
- =head2 PNG
- L<PNG TextualData tags|Image::ExifTool::TagNames/"PNG TextualData Tags"> are
- stored as tEXt, zTXt and iTXt chunks in PNG images. The tEXt and zTXt
- chunks use ISO 8859-1 encoding, while iTXt uses UTF-8. When reading,
- ExifTool converts all PNG textual data to the character set specified by the
- L</Charset> option. When writing, ExifTool generates a tEXt chunk (or zTXt
- with the L</Compress> option) if the text doesn't contain special characters
- or if Latin encoding is specified; otherwise an iTXt chunk is used and the
- text is converted from the specified character set and stored as UTF-8.
- =head2 JPEG Comment
- The encoding for the JPEG Comment (COM segment) is not specified, so
- ExifTool reads/writes this text without conversion.
- =head2 ID3
- The ID3v1 specification officially supports only ISO 8859-1 encoding (a
- subset of Windows Latin1), although some applications may incorrectly use
- other character sets. By default ExifTool converts ID3v1 text from Latin to
- the character set specified by the L</Charset> option. However, the
- internal ID3v1 charset may be specified with the L</CharsetID3> option. The
- encoding for ID3v2 information is stored in the file, so ExifTool converts
- ID3v2 text from this encoding to the character set specified by the
- L</Charset> option. ExifTool does not currently write ID3 information.
- =head2 PDF
- PDF text strings are stored in either PDFDocEncoding (similar to Windows
- Latin1) or Unicode (UCS-2). When reading, ExifTool converts to the
- character set specified by the L</Charset> option. When writing, ExifTool
- encodes input text from the specified character set as Unicode only if the
- string contains special characters, otherwise PDFDocEncoding is used.
- =head2 Photoshop
- Some Photoshop resource names are stored as Pascal strings with unknown
- encoding. By default, ExifTool assumes MacRoman encoding and converts this
- to UTF-8, but the internal and external character sets may be specified with
- L</CharsetPhotoshop> and L</Charset> options respectively.
- =head2 QuickTime
- QuickTime text strings may be stored in a variety of poorly document
- formats. ExifTool does its best to decode these according to the L</Charset>
- option setting. For some QuickTime strings, ExifTool assumes a default
- encoding of MacRoman, but this may be changed with the L</CharsetQuickTime>
- option.
- =head2 AIFF
- AIFF strings are assumed to be stored in MacRoman, and are converted
- according to the L</Charset> option when reading.
- =head2 MIE
- MIE strings are stored as either UTF-8 or ISO 8859-1. When reading, UTF-8
- strings are converted according to the L</Charset> option, and ISO 8859-1
- strings are never converted. When writing, input strings are converted from
- the specified character set to UTF-8. The resulting strings are stored as
- UTF-8 if they contain multi-byte UTF-8 character sequences, otherwise they
- are stored as ISO 8859-1.
- =head2 Vorbis
- Vorbis comments are stored as UTF-8, and are converted to the character set
- specified by the L</Charset> option.
- =head1 AUTHOR
- Copyright 2003-2016, Phil Harvey
- This library is free software; you can redistribute it and/or modify it
- under the same terms as Perl itself.
- =head1 ACKNOWLEDGEMENTS
- Many people have helped in the development of ExifTool through their bug
- reports, comments and suggestions, and/or additions to the code. See the
- ACKNOWLEDGEMENTS in the individual Image::ExifTool modules and in
- html/index.html of the Image::ExifTool distribution package for a list of
- people who have contributed to this project.
- =head1 SEE ALSO
- L<exiftool(1)|exiftool>,
- L<Image::ExifTool::TagNames(3pm)|Image::ExifTool::TagNames>,
- L<Image::ExifTool::Shortcuts(3pm)|Image::ExifTool::Shortcuts>,
- L<Image::ExifTool::Shift.pl|Image::ExifTool::Shift.pl>,
- L<Image::Info(3pm)|Image::Info>,
- L<Image::MetaData::JPEG(3pm)|Image::MetaData::JPEG>
- =cut
- # end
|