exiftool_vendored 10.65.0 → 11.41.0

data/bin/lib/Image/ExifTool.pod

@@ -5,7 +5,7 @@
 #
 # URL:          http://owl.phy.queensu.ca/~phil/exiftool/
 #
-# Legal:        Copyright (c) 2003-2017, Phil Harvey (phil at owl.phy.queensu.ca)
+# Legal:        Copyright (c) 2003-2019, 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.
 #------------------------------------------------------------------------------
@@ -55,7 +55,7 @@ Image::ExifTool - Read and write meta information
 
 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,
+Casio, DJI, FLIR, FujiFilm, GE, GoPro, 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.
@@ -65,43 +65,45 @@ supported by ExifTool (r = read, w = write, c = create):
 
   File Types
   ------------+-------------+-------------+-------------+------------
-  3FR   r     | DVB   r/w   | JSON  r     | OFR   r     | RTF   r
-  3G2   r/w   | DYLIB r     | K25   r     | OGG   r     | RW2   r/w
-  3GP   r/w   | EIP   r     | KDC   r     | OGV   r     | RWL   r/w
-  A     r     | EPS   r/w   | KEY   r     | OPUS  r     | RWZ   r
-  AA    r     | EPUB  r     | LA    r     | ORF   r/w   | RM    r
-  AAX   r/w   | ERF   r/w   | LFP   r     | OTF   r     | SEQ   r
-  ACR   r     | EXE   r     | LNK   r     | PAC   r     | SO    r
-  AFM   r     | EXIF  r/w/c | M2TS  r     | PAGES r     | SR2   r/w
-  AI    r/w   | EXR   r     | M4A/V r/w   | PBM   r/w   | SRF   r
-  AIFF  r     | EXV   r/w/c | MAX   r     | PCD   r     | SRW   r/w
-  APE   r     | F4A/V r/w   | MEF   r/w   | PDB   r     | SVG   r
-  ARW   r/w   | FFF   r/w   | MIE   r/w/c | PDF   r/w   | SWF   r
-  ASF   r     | FLA   r     | MIFF  r     | PEF   r/w   | THM   r/w
-  AVI   r     | FLAC  r     | MKA   r     | PFA   r     | TIFF  r/w
-  AZW   r     | FLIF  r/w   | MKS   r     | PFB   r     | TORRENT r
-  BMP   r     | FLV   r     | MKV   r     | PFM   r     | TTC   r
-  BPG   r     | FPF   r     | MNG   r/w   | PGF   r     | TTF   r
-  BTF   r     | FPX   r     | MOBI  r     | PGM   r/w   | VCF   r
-  CHM   r     | GIF   r/w   | MODD  r     | PLIST r     | VRD   r/w/c
-  COS   r     | GZ    r     | MOI   r     | PICT  r     | VSD   r
-  CR2   r/w   | HDP   r/w   | MOS   r/w   | PMP   r     | WAV   r
-  CRW   r/w   | HDR   r     | MOV   r/w   | PNG   r/w   | WDP   r/w
-  CS1   r/w   | HEIC  r     | MP3   r     | PPM   r/w   | WEBP  r
-  DCM   r     | HEIF  r     | MP4   r/w   | PPT   r     | WEBM  r
-  DCP   r/w   | HTML  r     | MPC   r     | PPTX  r     | WMA   r
-  DCR   r     | ICC   r/w/c | MPG   r     | PS    r/w   | WMV   r
-  DFONT r     | ICS   r     | MPO   r/w   | PSB   r/w   | WV    r
-  DIVX  r     | IDML  r     | MQV   r/w   | PSD   r/w   | X3F   r/w
-  DJVU  r     | IIQ   r/w   | MRW   r/w   | PSP   r     | XCF   r
-  DLL   r     | IND   r/w   | MXF   r     | QTIF  r/w   | XLS   r
-  DNG   r/w   | INX   r     | NEF   r/w   | RA    r     | XLSX  r
-  DOC   r     | ISO   r     | NRW   r/w   | RAF   r/w   | XMP   r/w/c
-  DOCX  r     | ITC   r     | NUMBERS r   | RAM   r     | ZIP   r
-  DPX   r     | J2C   r     | O     r     | RAR   r     |
-  DR4   r/w/c | JNG   r/w   | ODP   r     | RAW   r/w   |
-  DSS   r     | JP2   r/w   | ODS   r     | RIFF  r     |
-  DV    r     | JPEG  r/w   | ODT   r     | RSRC  r     |
+  3FR   r     | DSS   r     | J2C   r     | ODP   r     | RAW   r/w
+  3G2   r/w   | DV    r     | JNG   r/w   | ODS   r     | RIFF  r
+  3GP   r/w   | DVB   r/w   | JP2   r/w   | ODT   r     | RSRC  r
+  A     r     | DVR-MS r    | JPEG  r/w   | OFR   r     | RTF   r
+  AA    r     | DYLIB r     | JSON  r     | OGG   r     | RW2   r/w
+  AAE   r     | EIP   r     | K25   r     | OGV   r     | RWL   r/w
+  AAX   r/w   | EPS   r/w   | KDC   r     | OPUS  r     | RWZ   r
+  ACR   r     | EPUB  r     | KEY   r     | ORF   r/w   | RM    r
+  AFM   r     | ERF   r/w   | LA    r     | OTF   r     | SEQ   r
+  AI    r/w   | EXE   r     | LFP   r     | PAC   r     | SKETCH r
+  AIFF  r     | EXIF  r/w/c | LNK   r     | PAGES r     | SO    r
+  APE   r     | EXR   r     | LRV   r/w   | PBM   r/w   | SR2   r/w
+  ARQ   r/w   | EXV   r/w/c | M2TS  r     | PCD   r     | SRF   r
+  ARW   r/w   | F4A/V r/w   | M4A/V r/w   | PCX   r     | SRW   r/w
+  ASF   r     | FFF   r/w   | MAX   r     | PDB   r     | SVG   r
+  AVI   r     | FITS  r     | MEF   r/w   | PDF   r/w   | SWF   r
+  AZW   r     | FLA   r     | MIE   r/w/c | PEF   r/w   | THM   r/w
+  BMP   r     | FLAC  r     | MIFF  r     | PFA   r     | TIFF  r/w
+  BPG   r     | FLIF  r/w   | MKA   r     | PFB   r     | TORRENT r
+  BTF   r     | FLV   r     | MKS   r     | PFM   r     | TTC   r
+  CHM   r     | FPF   r     | MKV   r     | PGF   r     | TTF   r
+  COS   r     | FPX   r     | MNG   r/w   | PGM   r/w   | VCF   r
+  CR2   r/w   | GIF   r/w   | MOBI  r     | PLIST r     | VRD   r/w/c
+  CR3   r/w   | GPR   r/w   | MODD  r     | PICT  r     | VSD   r
+  CRM   r/w   | GZ    r     | MOI   r     | PMP   r     | WAV   r
+  CRW   r/w   | HDP   r/w   | MOS   r/w   | PNG   r/w   | WDP   r/w
+  CS1   r/w   | HDR   r     | MOV   r/w   | PPM   r/w   | WEBP  r
+  DCM   r     | HEIC  r     | MP3   r     | PPT   r     | WEBM  r
+  DCP   r/w   | HEIF  r     | MP4   r/w   | PPTX  r     | WMA   r
+  DCR   r     | HTML  r     | MPC   r     | PS    r/w   | WMV   r
+  DFONT r     | ICC   r/w/c | MPG   r     | PSB   r/w   | WTV   r
+  DIVX  r     | ICS   r     | MPO   r/w   | PSD   r/w   | WV    r
+  DJVU  r     | IDML  r     | MQV   r/w   | PSP   r     | X3F   r/w
+  DLL   r     | IIQ   r/w   | MRW   r/w   | QTIF  r/w   | XCF   r
+  DNG   r/w   | IND   r/w   | MXF   r     | R3D   r     | XLS   r
+  DOC   r     | INSV  r     | NEF   r/w   | RA    r     | XLSX  r
+  DOCX  r     | INX   r     | NRW   r/w   | RAF   r/w   | XMP   r/w/c
+  DPX   r     | ISO   r     | NUMBERS r   | RAM   r     | ZIP   r
+  DR4   r/w/c | ITC   r     | O     r     | RAR   r     |
 
   Meta Information
   ----------------------+----------------------+---------------------
@@ -294,19 +296,20 @@ 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.
+Reference to a hash containing the options settings valid for this call
+only.  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
+keys are identifiers -- essentially case-sensitive tag names with 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
+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>:
@@ -498,7 +501,7 @@ applications may use local encoding instead.  Default is 'Latin'.
 
 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'.
+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
@@ -523,11 +526,12 @@ without recoding.  Default is 0.
 
 =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.
+Option to write compact XMP output.  The XMP specification suggests that the
+data be padded with blanks to allow in-place editing. With this flag set to
+1, the 2 kB of padding is not written.  Note that this only effects embedded
+XMP since padding is never written for stand-alone XMP files.  When set to
+2, spaces to indent XMP for readability are also dropped.  Default is undef.
+Also see the XMPShorthand option for reducing the size of XMP.
 
 =item Composite
 
@@ -563,7 +567,7 @@ different when copying tags with L</SetNewValuesFromFile>.
 Format for printing date/time values.  See C<strftime> in the L<POSIX>
 package for details about the format string.  If date can not be converted,
 value is left unchanged unless the StrictDate option is set.  Timezones are
-ignored. The inverse conversion (ie. when calling L</SetNewValue>) is
+ignored.  The inverse conversion (ie. when calling L</SetNewValue>) is
 performed only if POSIX::strptime or Time::Piece is installed.  The default
 setting of undef causes date/time values to remain in standard EXIF format
 (similar to a DateFormat of "%Y:%m:%d %H:%M:%S").
@@ -605,8 +609,8 @@ XMP to be extracted.
 
 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.
+images in JPEG and MPO files, timed metadata in videos, and the resource
+fork of Mac OS files.  Default is undef.
 
 =item FastScan
 
@@ -615,19 +619,23 @@ 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.
+trailing metadata (eg. XMP written by some utilities) may be missed.  Also
+disables input buffering for some types of files to reduce memory usage when
+reading from a non-seekable stream.  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 or 4, only pseudo system tags and FileType are generated.  For 3,
+the file header is read to provide an educated guess at FileType.  For 4,
+the file is not read at all and FileType is determined based on the file's
+extension.  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.  The value is not changed if $_ is set to undef. 
-Applies to all returned values unless PrintConv option is disabled.
+variable as required.  The value is not changed if $_ is set to undef.  List
+items are filtered individually.  Applies to all returned values unless
+PrintConv option is disabled.
 
 =item FixBase
 
@@ -671,6 +679,14 @@ ignored if the PDOP is greater than this.  Default is undef.
 Minimum number of satellites for geotagging.  GPS fixes are ignored if the
 number of acquired satellites is less than this.  Default is undef.
 
+=item GeoSpeedRef
+
+Reference units for writing GPSSpeed when geotagging:
+
+    'K', 'k' or 'km/h'  - km/h
+    'M', 'm' or 'mph'   - mph
+    <anything else>     - knots (default undef)
+
 =item GlobalTimeShift
 
 Time shift to apply to all extracted date/time PrintConv values.  Does not
@@ -760,9 +776,10 @@ L<Image::ExifTool::TagNames/MacOS MDItem Tags> for more information).
 
 =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.
+Value for missing tags in tag name expressions (or tags where the advanced
+formatting expression returns undef).  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
 
@@ -803,18 +820,18 @@ Flag set to assume that QuickTime date/time values are stored as UTC,
 causing conversion to local time when they are extracted and from local time
 when written.  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.
+because they don't know the time zone), so the default is to not convert
+these times.  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>).  May be set to 2
-or 3 to enable generation of some additional tags mentioned in the tag name
-documentation.  Default is undef.
+or 3 to enable generation of some additional tags as mentioned in the tag
+name documentation.  Default is undef.
 
 =item RequestTags
 
@@ -858,10 +875,20 @@ Secondary sort order used for tags within each group when Sort is 'Group':
 Flag to return undefined value for any date which can't be converted when
 the DateFormat option is used.  Default is undef.
 
-  undef - Same as 0 for reading, 1 for copying
+  undef - Same as 0 for reading/writing, or 1 for copying
     0   - Return date/time value unchanged if it can't be converted
     1   - Return undef if date/time value can't be converted
 
+When set to 1 while writing a PrintConv date/time value with the DateFormat
+option set, the value is written only if POSIX::strptime or Time::Piece is
+available and can successfully convert the value.
+
+For PNG CreationTime, a setting of 1 has the additional effect of causing
+the date/time to be reformatted according to PNG 1.2 recommendation
+(RFC-1123) when writing, and a warning to be issued for any non-standard
+value when reading (but note that Windows may not recognize PNG date/time
+values in standard format).
+
 =item Struct
 
 Flag to return XMP structures as hash references instead of flattening into
@@ -885,6 +912,13 @@ FileDeviceID, FileBlockSize and FileBlockCount.
 Output file reference for Verbose and HtmlDump options.  Default is
 \*STDOUT.
 
+=item TimeZone
+
+Time zone for local date/time values.  May be set to any valid TZ string.
+Uses the system time zone if not specified.  Default is undef.  (Requires
+POSIX::tzset, which may not be available in Windows.  A work-around in
+Windows is to C<set TZ=E<lt>zoneE<gt>> before running ExifTool.)
+
 =item Unknown
 
 Flag to get the values of unknown tags.  If set to 1, unknown tags are
@@ -899,6 +933,7 @@ are:
 
   PARAM         - Get parameter
   PARAM=        - Clear parameter
+  PARAM^=       - Set parameter to empty string
   PARAM=VALUE   - Set parameter
   <hash ref>    - Set entire UserParam hash lookup
   undef         - Clear all user parameters
@@ -906,14 +941,15 @@ are:
 Where I<PARAM> is the user-defined parameter name (case insensitive).
 
 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 no additional arguments, C<Options('UserParam')> returns a reference
-to the hash of all user parameters (with lower-case names).
+the parameter name with a dollar sign just like normal tags, or via the API
+by calling C<Options('UserParam','PARAM')>.  If called without no additional
+arguments, C<Options('UserParam')> returns a reference to the hash of all
+user parameters (with lower-case names).
 
 =item Validate
 
-[Experimental] Flag to perform extra validation checks when reading, causing
-extra warnings to be generated if problems are found.  Default is undef.
+Flag to perform extra validation checks when reading, causing extra warnings
+to be generated if problems are found.  Default is undef.
 
 =item Verbose
 
@@ -948,6 +984,10 @@ and L<Image::ExifTool::TagNames/MacOS XAttr Tags> for more information).
 Flag to enable automatic conversion for unknown XMP tags with values that
 look like rational numbers or dates.  Default is 1.
 
+=item XMPShorthand
+
+Flag set to write xmp in shorthand format.  Default is undef.
+
 =back
 
 =item Return Values:
@@ -1128,7 +1168,8 @@ called with a source file name.
 The following ExifTool options are effective in the call to L</WriteInfo>:
 
 ByteOrder, Charset, CharsetEXIF, CharsetFileName, CharsetIPTC, Compact,
-Compress, FixBase, IgnoreMinorErrors, Password, PNGEarlyXMP and Verbose.
+Compress, FixBase, IgnoreMinorErrors, Password, PNGEarlyXMP, Verbose and
+XMPShorthand.
 
 =head2 GetTagList
 
@@ -1214,11 +1255,12 @@ Note that this list will be empty if tags were not specifically requested
 
 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.
+value, the original raw (Raw) value, or the original rational (Rational)
+value for rational formats.  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
@@ -1254,8 +1296,8 @@ optional group specifier), use L</GetInfo> instead.
 The following options are in effect when L</GetValue> is called:
 
 Charset, CoordFormat, DateFormat, Escape, Filter, GlobalTimeShift, Lang,
-ListItem, ListJoin, PrintConv, QuickTimeUTC (conversion to local time), and
-StrictDate.
+ListItem, ListJoin, PrintConv, QuickTimeUTC (conversion to local time),
+StrictDate and TimeZone.
 
 =over 4
 
@@ -1263,7 +1305,7 @@ StrictDate.
 
 0) ExifTool object reference
 
-1) Tag key
+1) Tag key, or case-sensitive tag name with optional group prefix(es)
 
 2) [optional] Value type: 'PrintConv', 'ValueConv', 'Both', 'Raw' or
 'Rational'
@@ -1510,7 +1552,7 @@ explicitly, either by group (with 'Adobe:*') or as a block (with 'Adobe').
 The following ExifTool options are effective in the call to L</SetNewValue>:
 
 Charset, DateFormat, Escape, IgnoreMinorErrors, Lang, ListJoin, ListSplit,
-PrintConv, QuickTimeUTC, StrictDate, Verbose and WriteMode.
+PrintConv, QuickTimeUTC, StrictDate, TimeZone, Verbose and WriteMode.
 
 =head2 GetNewValue
 
@@ -1609,13 +1651,15 @@ of this feature allows the tag value to be set from a string 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. 
+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 a Perl expression placed inside the braces and after a semicolon
-following the tag name (see the last example above).  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.
+following the tag name (see the last example above).  A '@' may be added
+after the tag name (before the semicolon) to make the expression act on
+individual list items instead of the concatenated string for list-type tags.
+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
@@ -1776,11 +1820,11 @@ systems only.
 
 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.
+Directory tags, or from the HardLink or SymLink 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);
@@ -1795,14 +1839,14 @@ precedence over any directory specified in FileName.
 
 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.
+3) [optional] 'HardLink' or 'SymLink' to create a hard or symbolic 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.
+1 on success, 0 if nothing was done, or -1 if there was an error renaming the
+file or creating the link.
 
 =item Notes:
 
@@ -1971,13 +2015,15 @@ 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.)
+main file.)  Document numbers are also used to differentiate samples for
+timed metadata in videos.
 
 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.
+family 4 group names of 'Copy1', 'Copy2', 'Copy3', etc.  For convenience,
+the primary tag may also be accessed using a group name of 'Copy0'.
 
 See L</GetAllGroups [static]> for complete lists of group names.
 
@@ -2150,51 +2196,54 @@ Here is a complete list of groups for each of these families:
 
 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, ISO, ITC, JFIF,
-JPEG, Jpeg2000, LNK, Leaf, Lytro, M2TS, MIE, MIFF, MNG, MOI, MPC, MPEG, MPF,
-MXF, MakerNotes, Matroska, Meta, Ogg, OpenEXR, Opus, 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
+EXE, EXIF, ExifTool, FITS, FLAC, FLIR, File, Flash, FlashPix, Font,
+FotoStation, GIF, GIMP, GeoTiff, GoPro, H264, HTML, ICC_Profile, ID3, IPTC,
+ISO, ITC, JFIF, JPEG, JSON, Jpeg2000, LNK, Leaf, Lytro, M2TS, MIE, MIFF,
+MNG, MOI, MPC, MPEG, MPF, MXF, MakerNotes, Matroska, Meta, Ogg, OpenEXR,
+Opus, PDF, PICT, PLIST, PNG, PSP, Palm, PanasonicRaw, PhotoCD,
+PhotoMechanic, Photoshop, PostScript, PrintIM, QuickTime, RAF, RIFF, RSRC,
+RTF, Radiance, Rawzor, Real, Red, SVG, SigmaRaw, Stim, Theora, Torrent,
+VCard, Vorbis, WTV, XML, XMP, ZIP
 
 =item Family 1 (Specific Location):
 
 AC3, AFCP, AIFF, APE, ASF, AVI1, Adobe, AdobeCM, AdobeDNG, Apple, Audible,
 CIFF, CameraIFD, Canon, CanonCustom, CanonRaw, CanonVRD, Casio, Chapter#,
 Composite, DICOM, DJI, 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#, ISO, ITC, InteropIFD, JFIF, JFXX, 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, MacOS, MakerNotes, MakerUnknown,
-Matroska, MediaJukebox, MetaIFD, Microsoft, Minolta, MinoltaRaw, Motorola,
-NITF, Nikon, NikonCapture, NikonCustom, NikonScan, Nintendo, Ocad, Ogg,
-Olympus, OpenEXR, Opus, 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#, VCalendar, VCard, Version0, Vorbis, XML, XMP,
-XMP-DICOM, XMP-GAudio, XMP-GImage, XMP-GPano, XMP-GSpherical, XMP-MP,
-XMP-MP1, XMP-PixelLive, XMP-aas, XMP-acdsee, XMP-album, XMP-apple-fi,
-XMP-aux, XMP-cc, XMP-cell, XMP-creatorAtom, XMP-crs, XMP-dc, XMP-dex,
-XMP-digiKam, XMP-drone-dji, 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-pmi, XMP-prism, XMP-prl, XMP-prm, 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
+ExifIFD, ExifTool, FITS, FLAC, FLIR, File, Flash, FlashPix, Font,
+FotoStation, FujiFilm, FujiIFD, GE, GIF, GIMP, GPS, GeoTiff, GlobParamIFD,
+GoPro, 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#, ISO, ITC, InteropIFD,
+ItemList, JFIF, JFXX, JPEG, JPEG-HDR, JSON, JVC, Jpeg2000, KDC_IFD, Keys,
+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, MS-DOC, MXF, MacOS, MakerNotes, MakerUnknown, Matroska,
+MediaJukebox, Meta, MetaIFD, Microsoft, Minolta, MinoltaRaw, Motorola, NITF,
+Nikon, NikonCapture, NikonCustom, NikonScan, Nintendo, Ocad, Ogg, Olympus,
+OpenEXR, Opus, 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, Red, Ricoh,
+SPIFF, SR2, SR2DataIFD, SR2SubIFD, SRF#, SVG, Samsung, Sanyo, Scalado,
+Sigma, SigmaRaw, Sony, SonyIDC, Stim, SubIFD, System, Theora, Torrent,
+Track#, UserData, VCalendar, VCard, Version0, Vorbis, WTV, XML, XMP,
+XMP-DICOM, XMP-GAudio, XMP-GDepth, XMP-GFocus, XMP-GImage, XMP-GPano,
+XMP-GSpherical, XMP-LImage, XMP-MP, XMP-MP1, XMP-PixelLive, XMP-aas,
+XMP-acdsee, XMP-album, XMP-apple-fi, XMP-aux, XMP-cc, XMP-cell,
+XMP-creatorAtom, XMP-crs, XMP-dc, XMP-dex, XMP-digiKam, XMP-drone-dji,
+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-pmi, XMP-prism, XMP-prl,
+XMP-prm, 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):
 
@@ -2229,22 +2278,27 @@ 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.
+APP4, APP5, APP6, APP7, APP8, APP9, Adobe, Audio, Author, CIFF, Camera,
+CanonVRD, Document, Ducky, EXIF, ExifIFD, ExifTool, File, FlashPix,
+FotoStation, GPS, GlobParamIFD, ICC_Profile, IFD0, IFD1, IPTC, Image,
+InteropIFD, JFIF, Jpeg2000, Location, MIE, MPF, MakerNotes, Meta, MetaIFD,
+NikonCapture, Other, PDF, PDF-update, PNG, PNG-pHYs, PhotoMechanic,
+Photoshop, Preview, PrintIM, Printing, RMETA, RSRC, SubIFD, Time, Trailer,
+Video, XML, XML-*, XMP, XMP-*
+
+To schedule a group for deletion, call L</SetNewValue> with a tag name like
+'EXIF:*' and an undefined tag value.
+
+Deleting a family 0 or 1 group will delete the entire corresponding block of
+metadata, but deleting a family 2 group (eg. Audio, Author, Camera, etc.)
+deletes the individual tags belonging to that category.
+
+The 'Trailer' group allows all trailers in JPEG and TIFF-format images to be
+deleted at once, including unknown trailers.  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
 
@@ -2261,9 +2315,10 @@ Get type of file given file name.
 
 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).
+1) [optional] Flag to return a description instead of a type.  Default is
+undef.  Set to 0 to also return types of recognized but unsupported files
+(otherwise the return value for unsupported files is undef), or 1 to return
+descriptions.
 
 =item Return Value:
 
@@ -2323,8 +2378,8 @@ files.
 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.
+Image::ExifTool distribution) because it allows tags to be added after a tag
+table has been initialized.
 
     use Image::ExifTool ':Public';
     my %tags = (
@@ -2568,7 +2623,7 @@ specified by the L</Charset> option.
 
 =head1 AUTHOR
 
-Copyright 2003-2017, Phil Harvey
+Copyright 2003-2019, Phil Harvey
 
 This library is free software; you can redistribute it and/or modify it
 under the same terms as Perl itself.