Metadata retention
Embedded metadata (EXIF, XMP, IPTC, the ICC colour profile, the orientation tag, resolution) travels with the source but not necessarily with the output. What an encoded file keeps is a typed MetadataPolicy selected with metadataPolicy(_:). It is terminal configuration: it does not change pixels, the last call wins, and it is applied identically by data(), write(to:) and writeChunks.
The policies
Section titled “The policies”| Policy | Result |
|---|---|
.default |
Removes EXIF, XMP, IPTC and comments; keeps the ICC profile, orientation and density, because they affect how an image displays. Privacy-minimising but rendering-safe. |
.preserveAll |
Keeps everything the format can carry. |
.removeAll |
Removes everything, including profile, orientation tag and density. Pixels are untouched, so an image that relied on one of them may display differently. |
| custom | MetadataPolicy(exif:icc:xmp:iptc:other:orientation:density:), each .preserve or .remove. |
// phone.jpg carries EXIF (camera make, software, orientation 6).let phone = try Hokusai(url: URL(fileURLWithPath: "phone.jpg"))
let policies: [(String, MetadataPolicy)] = [ ("default", .default), ("preserveAll", .preserveAll), ("removeAll", .removeAll), ("keep-exif-only", MetadataPolicy(exif: .preserve, icc: .remove, orientation: .remove)),]for (name, policy) in policies { let output = try await phone.jpeg().metadataPolicy(policy).data() let meta = try await Hokusai(data: output.data).metadata() print(name, "→ exif:", meta.exif?.count ?? 0, "bytes, orientation:", meta.orientation.map { "\($0)" } ?? "none", ", size", meta.width, "×", meta.height)}For phone.jpg (camera make and software in EXIF, orientation 6, 1000 × 1600 stored pixels) the output metadata read back was:
| Policy | EXIF bytes | Orientation |
|---|---|---|
.default |
126 | right (kept) |
.preserveAll |
162 | right |
.removeAll |
0 | none |
exif: .preserve, icc: .remove, orientation: .remove |
162 | up |
Details worth knowing
Section titled “Details worth knowing”- Orientation is not privacy metadata.
.removedeletes the tag without rotating pixels;autoOrient()applies it. If EXIF is kept in full, removing the orientation writes the neutral value “up” (as the last row shows). With the default policy, the EXIF block that remains is a minimal one: the orientation and the technical entries libvips writes itself, with none of the descriptive or location fields. - Density. Formats always record some resolution, so
.removestops the source’s from being carried over and the encoder writes its own default. - ICC retention is not a colour conversion: no profile is applied, attached or changed.
- Earlier versions removed everything including the profile; since the default changed, an image with a profile keeps it.
What each format can carry
Section titled “What each format can carry”| EXIF | XMP | IPTC | ICC | Orientation | Density | |
|---|---|---|---|---|---|---|
| JPEG | yes | yes | yes | yes | EXIF tag | yes |
| PNG | yes | yes | no | yes | EXIF tag | yes |
| WebP | yes | yes | no | yes | EXIF tag | no |
| AVIF | yes | yes | no | yes | container rotation | no |
A family a format cannot carry is simply absent from its output. AVIF is the exception for orientation: it stores a rotation of the container rather than a tag, and a reader applies it and reports no tag. Whether libvips writes that rotation depends on the build (libvips 8.18 does; the 8.16 baseline keeps the orientation only as an EXIF tag that AVIF viewers ignore). For AVIF on such a build, call autoOrient() first so the pixels are upright.
Related
Section titled “Related”- Inspection: what the source contained
- Upload normalisation recipe