80 KiB
EXIV2(1)
NAME
exiv2 - Image metadata manipulation tool
SYNOPSIS
exiv2 [ options ] [ action ] file ...
DESCRIPTION
exiv2 is a program to read and write image metadata, including Exif, IPTC, XMP, image comments, ICC Profile, thumbnails, image previews and many vendor makernote tags. The program optionally converts between Exif tags, IPTC datasets and XMP properties as recommended by the Exif Standard, the IPTC Standard, the XMP specification and the Metadata Working Group guidelines.
TABLE OF CONTENTS
- SYNOPSIS
- DESCRIPTION
- FILE TYPES
- ACTIONS
- COMMAND SUMMARY
- OPTIONS
- 'MODIFY' COMMANDS
- EXIV2 GROUPS, TYPES AND VALUES
- CONFIGURATION FILE
- EXAMPLES
- ENVIRONMENT
- NOTES
- BUGS
- COPYRIGHT
- SEE ALSO
- AUTHORS
FILE TYPES
The following image formats and metadata categories are supported:
| Type | Exif | IPTC | XMP | Image Comments | ICC Profile | Thumbnail |
|---|---|---|---|---|---|---|
| ARW | Read | Read | Read | - | - | Read |
| AVIF | Read | Read | Read | - | - | Read |
| BMP | - | - | - | - | - | - |
| CR2 | Read/Write | Read/Write | Read/Write | - | Read/Write | Read/Write |
| CR3 | Read | Read | Read | - | Read | Read |
| CRW | Read/Write | - | - | Read/Write | - | Read/Write |
| DNG | Read/Write | Read/Write | Read/Write | - | Read/Write | Read/Write |
| EPS | - | - | Read/Write | - | - | |
| EXV | Read/Write | Read/Write | Read/Write | Read/Write | Read/Write | Read/Write |
| GIF | - | - | - | - | - | - |
| HEIC | Read | Read | Read | - | - | Read |
| HEIF | Read | Read | Read | - | - | Read |
| JP2 | Read/Write | Read/Write | Read/Write | - | Read/Write | Read/Write |
| JPEG | Read/Write | Read/Write | Read/Write | Read/Write | Read/Write | Read/Write |
| MRW | Read | Read | Read | - | - | Read |
| NEF | Read/Write | Read/Write | Read/Write | - | Read/Write | Read/Write |
| ORF | Read/Write | Read/Write | Read/Write | - | - | Read/Write |
| PEF | Read/Write | Read/Write | Read/Write | - | Read/Write | Read/Write |
| PGF | Read/Write | Read/Write | Read/Write | Read/Write | Read/Write | - |
| PNG | - | Read/Write | Read/Write | - | Read/Write | Read/Write |
| PSD | Read/Write | Read/Write | Read/Write | - | - | Read/Write |
| RAF | Read | Read | Read | - | - | Read |
| RW2 | Read | Read | Read | - | - | Read |
| SR2 | Read | Read | Read | - | - | Read |
| SRW | Read/Write | Read/Write | Read/Write | - | - | Read/Write |
| TGA | - | - | - | - | - | - |
| TIFF | Read/Write | Read/Write | Read/Write | - | Read/Write | Read/Write |
| WEBP | Read/Write | - | Read/Write | - | Read/Write | Read/Write |
| XMP | - | - | Read/Write | - | - | - |
-
Support for GIF, TGA and BMP images is minimal: the image format is recognized, a MIME type assigned to it and the height and width of the image are determined.
-
Reading other TIFF-like RAW image formats, which are not listed in the table, may also work.
-
The thumbnail, if available, is included in the list of image previews.
ACTIONS
The action argument is only required if it is not clear from the options which action is implied.
pr | print
Print image metadata. This is the default action, i.e. the command
exiv2 image.jpg will print a summary of the image Exif metadata.
ex | extract
Extract metadata to *.exv, XMP sidecar (*.xmp), preview image, thumbnail or ICC profile file. Modification commands can be applied on-the-fly.
in | insert
Insert metadata from corresponding *.exv, XMP sidecar (*.xmp), thumbnail or ICC profile files. Use option --suffix suf to change the suffix of the input files. Since files of any supported format can be used as input files, this command can be used to copy the metadata between files of different formats. Modification commands can be applied on-the-fly.
rm | delete
Delete image metadata from the files.
ad | adjust
Adjust Exif timestamps by the given time. Requires at least one of the options --adjust time, --years +-n, --months +-n or --days +-n. See TZ environment variable.
mo | modify
Apply commands to modify (add, set, delete) the Exif, IPTC and XMP metadata of image files. Requires option --comment txt, --modify cmdfile or --Modify cmd.
mv | rename
Rename files and/or set file timestamps according to the Exif create timestamp. Uses the value of tag Exif.Photo.DateTimeOriginal or, if not present, Exif.Image.DateTime to determine the timestamp. The filename format can be set with --rename fmt, timestamp options are --timestamp and --Timestamp. See TZ environment variable.
fi | fixiso
Copy the ISO setting from one of the proprietary Nikon or Canon makernote ISO tags to the regular Exif ISO tag, Exif.Photo.ISOSpeedRatings. Does not overwrite an existing Exif ISO tag.
fc | fixcom
Fix the character encoding of Exif Unicode user comments. Decodes the comment using the auto-detected or specified character encoding and writes it back in UCS-2. Use option --encode enc to specify the current encoding of the comment if necessary.
COMMAND SUMMARY
exiv2 [ option [ arg ] ]+ [ action ] file ...
Where file contains image metadata, optionally specified using a URL (http, https, ftp, sftp, data and file supported) or a wildcard pattern (e.g., *.jpg)
| Option | Long option | Description |
|---|---|---|
| -a time | --adjust time | Automatically modify metadata time stamps. For the adjust action [...] |
| -b | --binary | Obsolete and should not be used. Reserved for use with the test suite |
| -c txt | --comment txt | JPEG comment string to set in the image. For the modify action [...] |
| -d tgt1 | --delete tgt1 | Delete target(s) for the delete action [...] |
| -D +-n | --days +-n | Automated adjustment of the days in metadata dates [...] |
| -e tgt3 | --extract tgt3 | Extract target(s) for the extract action [...] |
| -f | --force | Do not prompt before overwriting existing files. For the rename and extract actions [...] |
| -F | --Force | Do not prompt before renaming files. For the rename and extract actions [...] |
| -g str | --grep str | Only output where str matches in output text [...] |
| -h | --help | Display help and exit [...] |
| -i tgt2 | --insert tgt2 | Insert target(s) for the insert action [...] |
| -k | --keep | Preserve file timestamps when updating files [...] |
| -K key | --key key | Report a key. Similar to --grep str, however key must match exactly [...] |
| -l dir | --location dir | Location (directory) for files to be inserted or extracted [...] |
| -m cmdfile | --modify cmdfile | Read commands from a file. For the modify action [...] |
| -M cmd | --Modify cmd | Modify the metadata with the command. For the modify action [...] |
| -n enc | --encode enc | Charset to decode Exif Unicode user comments [...] |
| -O +-n | --months +-n | Automated adjustment of the months in metadata dates [...] |
| -p mod | --print mod | Print report (common reports) [...] |
| -P flg | --Print flg | Print report (fine grained control) [...] |
| -q | --quiet | Silence warnings and error messages [...] |
| -Q lvl | --log lvl | Set the log-level to 'd'(ebug), 'i'(nfo), 'w'(arning), 'e'(rror) or 'm'(ute) [...] |
| -r fmt | --rename fmt | Filename format for the rename action [...] |
| -S suf | --suffix suf | Use suffix for source files when using the insert command [...] |
| -t | --timestamp | Set the file timestamp from Exif metadata. For the rename action [...] |
| -T | --Timestamp | Only set the file timestamp from Exif metadata. For the rename action [...] |
| -u | --unknown | Show unknown tags [...] |
| -v | --verbose | Verbose [...] |
| -V | --version | Show the program version and exit [...] |
| -Y +-n | --years +-n | Automated adjustment of the years in metadata dates [...] |
The flags for those options are:
| Parameter | Description |
|---|---|
| action | pr | ex | in | rm | ad | mo | mv | fi | fc (print, extract, insert, delete, adjust, modify, rename, fixiso, fixcom) |
| cmd | (set | add) key [[type] value] | del key [type] | reg prefix namespace (see 'Modify' command format) |
| enc | Values defined in iconv_open(3) (e.g., UTF-8) |
| flg | E | I | X | x | g | k | l | n | y | c | s | v | t | h (Exif, IPTC, XMP, num, grp, key, label, name, type, count, size, vanilla, translated, hex) |
| fmt | Default format: %Y%m%d_%H%M%S |
| key | See Exiv2 key syntax) |
| lvl | d | i | w | e (debug, info, warning, error) |
| mod | s | a | e | t | v | h | i | x | c | p | C | R | S | X (summary, all, Exif, translated, vanilla, hex, IPTC, XMP, comment, preview, ICC Profile, Recursive Structure, Simple Structure, raw XMP) |
| suf | '.' then the file's extension (e.g., '.txt') |
| time | [ +|-]HH[:MM[:SS[.mmm]]] (Default is + when +/- are missing) |
| tgt1 | a | c | e | i | I | t | x | C | - (all, comment, Exif, IPTC, IPTC all, thumbnail, XMP, ICC Profile, stdin/out) |
| tgt2 | a | c | e | i | t | x | C | X | XX | - (all, comment, Exif, IPTC, thumbnail, XMP, ICC Profile, SideCar, Raw XMP, stdin/out) |
| tgt3 | a | e | i | p | t | x | C | X | XX | - (all, Exif, IPTC, preview, thumbnail, XMP, ICC Profile, SideCar, Raw XMP, stdin/out) |
| type | An Exif, IPTC or XMP tag type (e.g., xmpText). See Exif/IPTC/XMP types |
| +-n | The amount to change in the date (e.g., -3). Default is + when +/- are missing |
OPTIONS
-h, --help
Display help and exit.
-V, --version
Show the program version and exit.
When --version is combined with --verbose, build information is printed to standard output along with a list of shared libraries which have been loaded into memory. Verbose version is supported on Windows (MSVC, Cygwin and MinGW builds), macOS and Linux and is provided for test and debugging. The library name and version number are always printed, even if output is filtered with --grep str.
-v, --verbose
Be verbose during the program run.
-q, --quiet
Silence warnings and error messages during the program run. Note that options --quiet and --verbose can be used at the same time.
-Q lvl, --log lvl
Set the log-level to 'd'(ebug), 'i'(nfo), 'w'(arning), 'e'(rror) or 'm'(ute), with the lvl chosen including those below it ('d' <- 'i' <- 'w' <- 'e'). The default log-level is 'w'. --log m is equivalent to --quiet. All log messages are written to standard error.
-u, --unknown
Show unknown tags. Default is to suppress tags which don't have a name (e.g., Exif.SonyMisc3c.0x022b).
-g str, --grep str
When printing tags, display only those where str is found in the key (see Exiv2 key syntax). When --grep str is used with --verbose --version, lines are included where str matches in the variable or value.
Multiple --grep str options can be used to output additional data:
$ exiv2 --verbose --version --grep webready --grep time
exiv2 1.0.0.9
time=11:01:53
enable_webready=1
xmlns=mediapro:http://ns.iview-multimedia.com/mediapro/1.0/
When the --print mod and --Print flgs options are not specified, the default is --print a:
$ curl --silent -O https://clanmills.com/Stonehenge.jpg
$ exiv2 --grep Date Stonehenge.jpg
Exif.Image.DateTime Ascii 20 2015:07:16 20:25:28
Exif.Photo.DateTimeOriginal Ascii 20 2015:07:16 15:38:54
Exif.Photo.DateTimeDigitized Ascii 20 2015:07:16 15:38:54
Exif.NikonWt.DateDisplayFormat Byte 1 Y/M/D
Exif.GPSInfo.GPSDateStamp Ascii 11 2015:07:16
Xmp.xmp.ModifyDate XmpText 25 2015-07-16T20:25:28+01:00
You may use --print mod or --Print flgs to further filter output (--print s is ignored):
$ exiv2 --print x --grep Date Stonehenge.jpg
Xmp.xmp.ModifyDate XmpText 25 2015-07-16T20:25:28+01:00
str can contain an optional /i modifier at the end, to indicate case insensitivity:
$ exiv2 --print px --grep date/i Stonehenge.jpg
Xmp.xmp.ModifyDate XmpText 25 2015-07-16T20:25:28+01:00
-K key, --key key
Only reports tags for a given key, which must match the key exactly (See Exiv2 key syntax).
Multiple --key key options can be used to report more than a single key:
$ curl --silent -O https://clanmills.com/Stonehenge.jpg
$ exiv2 --key Exif.Photo.DateTimeDigitized --key Exif.Photo.DateTimeOriginal Stonehenge.jpg
Exif.Photo.DateTimeOriginal Ascii 20 2015:07:16 15:38:54
Exif.Photo.DateTimeDigitized Ascii 20 2015:07:16 15:38:54
-n enc, --encode enc
Charset to use when decoding Exif Unicode user comments, where enc is a name understood by iconv_open(3) (e.g., 'UTF-8').
-k, --keep
Preserve file timestamps when updating files. Can be used with all options which update files and is ignored by read-only options.
-t, --timestamp
Set the file timestamp according to the Exif create timestamp in addition to renaming the file (overrides --keep). This option is only used with the rename action. See TZ environment variable.
-T, --Timestamp
Only set the file timestamp according to the Exif create timestamp, do not rename the file (overrides --keep). This option is only used with the rename action. See TZ environment variable.
-f, --force or -F, --Force
These options are used by the rename and extract actions to determine the file overwrite policy. The options override the default behavior, which is to prompt the user if the filename already exists. These options are usually combined with --verbose, to provide additional status output.
The rename action will overwrite files when --force is used. Instead, if --Force is used and the file already exists, the new filename is appended with '_1' ('_2', ...) to prevent data loss.
The extract action will overwrite files when either --force or --Force is used.
For example, renaming a file using --Force, where the same filename has already been renamed:
$ curl --silent -O https://clanmills.com/Stonehenge.jpg
$ exiv2 --verbose --Force rename Stonehenge.jpg
File 1/1: Stonehenge.jpg
Renaming file to ./20150716_153854.jpg
$ curl --silent -O https://clanmills.com/Stonehenge.jpg
$ exiv2 --verbose --Force rename Stonehenge.jpg
File 1/1: Stonehenge.jpg
Renaming file to ./20150716_153854_1.jpg
-r fmt, --rename fmt
Filename format for the rename action (See TZ environment variable). The fmt string follows the definitions in strftime(3), using Exif.Photo.DateTimeOriginal or Exif.Image.DateTime as the reference date and time. In addition, the following special character sequences are also provided:
| Variable | Description |
|---|---|
| :basename: | Original filename without extension |
| :dirname: | Name of the directory holding the original file |
| :parentname: | Name of parent directory |
The default fmt is %Y%m%d_%H%M%S
For example, renaming a file when fmt is made up of the basename, day, short month and long year:
$ curl --silent -O https://clanmills.com/Stonehenge.jpg
$ exiv2 --verbose --rename ':basename:_%d_%b_%Y' Stonehenge.jpg
File 1/1: Stonehenge.jpg
Renaming file to ./Stonehenge_16_Jul_2015.jpg
If the filename to rename to already exists and --Force and --force are not used, the user is prompted for an action.
| Option | Description |
|---|---|
| [O]verwrite | Rename the file, overriding the existing one |
| [r]ename | Rename the file, but append '_1' ('_2', ...) to the new filename |
| [s]kip : | Cancel renaming this file |
For example, when renaming a second Stonehenge.jpg file:
$ curl --silent -O https://clanmills.com/Stonehenge.jpg
$ exiv2 --verbose --rename ':basename:_%d_%b_%Y' Stonehenge.jpg
File 1/1: Stonehenge.jpg
exiv2.exe: File `./Stonehenge_16_Jul_2015.jpg' exists. [O]verwrite, [r]ename or [s]kip? r
Renaming file to ./Stonehenge_16_Jul_2015_1.jpg
-a time, --adjust time
Time adjustment, where time is in the format [-]HH[:MM[:SS]]. This option is only used with the adjust action. See TZ environment variable.
Examples of time are:
| Time | Description |
|---|---|
| +1 | Adds one hour |
| 1:01 | Adds one hour and one minute |
| -0:00:30 | Subtracts 30 seconds |
-Y +-n, --years +-n
Time adjustment by a positive or negative number of years, for the adjust action. See TZ environment variable.
-O +-n, --months +-n
Time adjustment by a positive or negative number of months, for the adjust action. See TZ environment variable.
-D +-n, --days +-n
Time adjustment by a positive or negative number of days, for the adjust action. See TZ environment variable.
-p mod, --print mod
Print mode for the print action (see DESCRIPTION, for metadata support in a file type). Possible modes are:
| Option | Description |
|---|---|
| s | A summary of the Exif metadata (the default for the print action) |
| a | Exif, IPTC and XMP metadata (shortcut for --Print kyct) |
| e | Exif metadata (shortcut for --Print Ekycv) |
| t | Interpreted (translated) Exif tag values (shortcut for --Print Ekyct) |
| v | Plain (untranslated) Exif tag values (shortcut for --Print Exgnycv) |
| h | Hex dump of the Exif data (shortcut for --Print Exgnycsh) |
| i | IPTC datasets (shortcut for --Print Ikyct) |
| x | XMP properties (shortcut for --Print Xkyct) |
| c | JPEG comment |
| p | List available image previews, sorted by size in pixels (e.g., see --extract tgt3) |
| C | Image ICC Profile |
| R | Print image structure recursively (only for the 'debug' build with jpg, png, tiff, webp, cr2 and jp2 types) |
| S | Image structure information (jpg, png, tiff, webp, cr2 and jp2 types only) |
| X | "raw" XMP |
--print mod can be combined with --grep str or --key key to further filter the output.
For the order of the columns in the output, see --Print flgs.
-P flgs, -Print flgs
Print flags allows fine control of the tag list for the print action (see DESCRIPTION, for metadata support in a file type). The option allows control of the type of metadata as well as data columns included in the print output. Valid flags are:
| Option | Description |
|---|---|
| E | Exif tags |
| I | IPTC datasets |
| X | XMP properties |
| x | Tag number for Exif or IPTC tags (in hexadecimal) |
| g | Group name (e.g., for Exif.Photo.UserComment, outputs Photo) |
| k | Key (e.g., Exif.Photo.UserComment) |
| l | Tag label (human readable tagname, e.g., for Exif.Photo.UserComment, outputs 'User comment') |
| n | Tagname (e.g., for Exif.Photo.UserComment, outputs UserComment) |
| y | Type (for available types, see Exif/IPTC/XMP types |
| c | Number of components (for single entry types, the number of sizeof('type') in 'size'. For multi-entry types, the number of entries. See Exif/IPTC/XMP types) |
| s | Size in bytes |
| v | Plain data value (vanilla values, i.e., untranslated) |
| V | Plain data value AND the word 'set ' (see 'MODIFY' COMMANDS |
| t | Interpreted (translated) human readable data values |
| h | Hex dump of the data |
The order of the values in flgs is not respected, with output displayed as follows:
Tag number (x) | Plain 'set' (V) | Group (g) | Key (k) | Tagname (n) | Tagname label (l) | Type (y) | Components (c) | Size (s) | Value (E, I, X, v, t)
For example, displaying the IPTC tags in a file:
$ curl --silent -O https://clanmills.com/Stonehenge.jpg
$ exiv2 --Print xgknlycsIt Stonehenge.jpg
0x0000 Envelope Iptc.Envelope.ModelVersion ModelVersion Model Version Short 1 2 4
0x005a Envelope Iptc.Envelope.CharacterSet CharacterSet Character Set String 3 3
0x0000 Application2 Iptc.Application2.RecordVersion RecordVersion Record Version Short 1 2 4
0x0078 Application2 Iptc.Application2.Caption Caption Caption String 12 12 Classic View
--Print flgs can be combined with --grep str or --key key to further filter the output.
-d tgt1*, --delete tgt1
Delete target(s) for the delete action. Possible targets are:
| Option | Description |
|---|---|
| a | All supported metadata (the default for the delete action) |
| e | Exif section |
| t | Exif thumbnail only |
| i | IPTC data |
| x | XMP packet |
| c | JPEG comment |
| C | ICC Profile |
| I | All IPTC data (removes broken metadata containing multiple IPTC blocks) |
-i tgt2, --insert tgt2
Insert target(s) for the insert action (see DESCRIPTION, for metadata support in a file type). Possible targets are:
| Option | Description |
|---|---|
| a | All supported metadata (the default for the insert action) |
| e | Exif section |
| t | Exif thumbnail. Only JPEG thumbnails can be inserted from a file called file-thumb.jpg |
| i | IPTC data |
| x | XMP packet |
| c | JPEG comment |
| C | ICC Profile, inserted from a file called .icc |
| X | Insert metadata from an XMP sidecar file, .xmp. The remaining targets determine which metadata to include, possible are Exif, IPTC and XMP (default is all of these). Inserted XMP properties include those converted to Exif and IPTC |
| XX | Insert "raw" XMP metadata from a sidecar file, .exv |
| - | Insert from stdin. This option is intended for "filter" operations |
Filter operations between extract and insert are possible, using the following template; xmllint(1) can be optionally used when extracting XMP sidecar files:
$ exiv2 -e{tgt3}- filename | [ xmllint .... |] exiv2 -i{tgt2}- filename
-e tgt3, --extract tgt3
Extract target(s) for the extract action. Possible targets are:
Option |
Description |
|---|---|
| a | All supported metadata (the default for the extract action) |
| e | Exif section |
| t | Extract Exif thumbnail only to a file called -thumb.jpg |
| i | IPTC data |
| x | XMP packet |
| c | JPEG comment |
| p[<n>[,<m> ...]] | Extract preview images to files called <file>-preview<n | m | ...>.jpg (--extract p extracts all previews). The thumbnail is included in any preview images |
| C | Extract ICC profile, to a file called .icc |
| X | Insert metadata from an XMP sidecar file, .xmp. The remaining targets determine which metadata to include, possible are Exif, IPTC and XMP (default is all of these). Inserted XMP properties include those converted to Exif and IPTC |
| XX | Extract "raw" XMP metadata to a sidecar . Other targets cannot be used with this, as only XMP data is written |
| - | Output to stdout (see --insert tgt2 for an example of this feature) |
When extracting preview images, first list which previews are available:
$ curl --silent -O https://clanmills.com/Stonehenge.jpg
$ exiv2 --print p Stonehenge.jpg
Preview 1: image/jpeg, 160x120 pixels, 10837 bytes
then extract the preview by number (in this case, preview 1 is also the thumbnail):
$ exiv2 --verbose --extract p1 Stonehenge.jpg
File 1/1: Stonehenge.jpg
Writing preview 1 (image/jpeg, 160x120 pixels, 10837 bytes) to file ./Stonehenge-preview1.jpg
-c txt, --comment txt
JPEG comment string to set in the image (modify action). This option can also be used with the extract and insert actions to modify metadata on-the-fly.
-m cmdfile, --modify cmdfile
Commands for the modify action (see Command file format). In the format:
--modify ( file | - )
| Parameter | Description |
|---|---|
| file | The file containing the 'modify' commands |
| - | Stdin |
This option can also be used with the extract and insert actions to modify metadata on-the-fly. See 'MODIFY' COMMANDS.
-M cmd, --Modify cmd
Command line for the modify action. This option can also be used with the extract and insert actions to modify metadata on-the-fly. See 'MODIFY' COMMANDS and 'Modify' command file.
-l dir, --location dir
Location (directory) for files to be inserted from or extracted to.
-S suf, --suffix suf
Use suffix suf for source files when using insert action (e.g., '.txt').
'MODIFY' COMMANDS
Tags can be altered using the 'modify' action and --Modify cmd or --modify cmdfile.
For example, adding an IPTC tag on the command line:
$ curl --silent -O https://clanmills.com/Stonehenge.jpg
$ exiv2 --Modify "add Iptc.Application2.Credit String Mr. Mills" Stonehenge.jpg
or applying a set of 'modify' commands from a file (see 'Modify' command File):
$ exiv2 --modify cmd.txt Stonehenge.jpg
Multiple --Modify cmd and --modify cmdfile options can be combined together, with the changes applied left to right on each file. For example, applying one command line 'modify' then a 'modify' command file, then another command line 'modify':
$ exiv2 --Modify "set Iptc.Application2.Caption Stonehenge" --modify cmdfile.txt --Modify "add Iptc.Application2.Keywords Monument" Stonehenge.jpg
A list of modify commands can be generated from an existing file using --Print Vkyv. For example, only displaying the 'dc' 'modify' commands:
$ exiv2 --Print Vkyv --grep dc Stonehenge.jpg
set Xmp.dc.description LangAlt lang="x-default" Classic View
set Xmp.dc.Family XmpBag Robin
Using --modify -, a command file can be read from stdin instead of being a named file. For example:
$ cat cmdfile.txt | exiv2 --modify - Stonehenge.jpg
When modifying, only a correct metadata structure is enforced and it is possible to write tags with types and values different from those specified in the standards. This can include incorrect types (e.g., change Exif.Image.DateTime to a Float), duplicate Exif tags or incomplete metadata (e.g., deleting Exif.GPSInfo.GPSLatitudeRef, which works together with Exif.GPSInfo.GPSLatitude). While exiv2 is able to read all metadata that it can write, other programs may have difficulties with images that contain non standards-defined metadata.
Quotations with 'modify' commands
With --Modify cmd, quotation marks are use to surround the
cmd. The Windows command line requires double quotes to be
used, however generally, quotes inside that string, can be either single
or double. Generally, UNIX based systems can use pairs of single or
double quotes in any position. In both systems, inner string quotation
marks may need to use the \ escape sequence.
See note on quotations when using XMP LangAlt values.
'Modify' command format
The format of a command is:
( set | add ) key [ [ type ] value ] | del key [ type ] | reg prefix namespace
Where:
| Option | Description |
|---|---|
| add | Adds a tag. For Exif and IPTC repeatable tags, this adds a new tag, otherwise this replaces any existing tag (see Multiple elements and Duplicate Exif tags) |
| set | Set the value of an existing tag with a matching key or if undefined, add the tag. If Duplicate Exif or IPTC repeatable tags already exist, this replaces them (see Multiple elements) |
| del | Delete all occurrences of a tag that matches key, including any duplicate tags |
| reg | Registers an XMP namespace with an XMP prefix (see XMP namespaces) If registering an existing prefix with a different namespace, then the namespace is updated |
using the parameters:
| Parameter | Description |
|---|---|
| key | An Exif, IPTC or XMP key (see Exiv2 key syntax) |
| type | The type for the tag, a default is used if none is given. For built-in tags, the default is defined in the standard and for registered XMP tags, the default is XmpText (see Exif/IPTC/XMP types) |
| value | The remaining text on the line is the value, and can optionally be enclosed in quotes (see Quotations with 'modify' commands). For Ascii, XmpAlt, XmpBag, XmpSeq and XmpText, the value is optional which is equivalent to an empty value ("") |
| prefix | This is the XMP 'Group' that is being registered. This is case sensitive and must be unique within an image's metadata. e.g., For an "Exiv2" prefix, the tags for that group are available as Xmp.Exiv2.Tagname |
| namespace | An identifier for the prefix. This is case sensitive and must be unique within an image's metadata. Built-in namespaces use a URL format, but they are not required to exist |
'Modify' examples
Setting a Rational or SRational value
For the 'Rational' and 'SRational' formats, see Exif/IPTC/XMP types.
For example, modifying a 'Rational' number:
$ curl --silent -O https://clanmills.com/Stonehenge.jpg
$ exiv2 --Modify"set Exif.Photo.MaxApertureValue 2485427/500000" Stonehenge.jpg
Setting an aperture value
Exif aperture values are stored in an apex-value format and when using the translated print option, are output as an Fnumber value. The APEX Fnumber translations use the formulae (in base 2):
apex-value = log(Fnumber) * 2.0 / log(2.0)
Fnumber = exp(apex-value * log(2.0) / 2.0)
The apex-value is a Rational and can be modified as shown in Setting a Rational or SRational value, however a convenience method is also provided to set an Fnumber directly. This uses the format:
F <value>
Where <value> is either an integer or decimal number.
For example, the following 'modify' will produce the same value as Setting a Rational or SRational value. This is displayed in vanilla and translated output:
$ curl --silent -O https://clanmills.com/Stonehenge.jpg
$ exiv2 --Modify "set Exif.Photo.MaxApertureValue F5.6" Stonehenge.jpg
$ exiv2 --print e --grep MaxApertureValue Stonehenge.jpg
Exif.Photo.MaxApertureValue Rational 1 2485427/500000
$ exiv2 --print t --grep MaxApertureValue Stonehenge.jpg
Exif.Photo.MaxApertureValue Rational 1 F5.6
More information about APEX values is available from: http://en.wikipedia.org/wiki/APEX_system
Setting a Comment value
For the 'Comment' format, see Exif 'Comment' values.
For example, to set an Ascii comment:
$ curl --silent -O https://clanmills.com/Stonehenge.jpg
$ exiv2 --Modify "set Exif.Photo.UserComment charset=Ascii Photo" Stonehenge.jpg
$ exiv2 --grep UserComment Stonehenge.jpg
Exif.Photo.UserComment Undefined 13 charset=Ascii Photo
or a Unicode comment:
$ exiv2 --Modify "set Exif.GPSInfo.GPSProcessingMethod charset=Unicode \\u0047\\u0050\\u0053" Stonehenge.jpg
$ exiv2 --grep GPSProcessingMethod Stonehenge.jpg
Exif.GPSInfo.GPSProcessingMethod Undefined 14 charset=Unicode GPS
Registering an XMP namespace
For help with namespaces, see XMP namespaces.
Each XMP namespace has a prefix associated with it. For example, when modifying, this is declared using the string:
--Modify "reg myPrefix http://ns.myPrefix.me/"
When a non-standard group or tag belonging to that group is modified, the appropriate 'reg' 'modify' command must be included before that. For example, adding a myPhotos group with a weather tag and values:
$ curl --silent -O https://clanmills.com/Stonehenge.jpg
$ exiv2 --Modify "reg myPhotos http://ns.myPhotos.org/" --Modify "add Xmp.myPhotos.weather XmpBag Cloudy" Stonehenge.jpg
$ exiv2 --Modify "reg myPhotos http://ns.myPhotos.org/" --Modify "set Xmp.myPhotos.weather XmpBag Sunny" Stonehenge.jpg
$ exiv2 --Modify "reg myPhotos http://ns.myPhotos.org/" --Modify "set Xmp.myPhotos.weather XmpBag Hot" Stonehenge.jpg
$ exiv2 --grep myPhotos Stonehenge.jpg
Xmp.myPhotos.weather XmpBag 3 Cloudy, Sunny, Hot
